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by Nicholas C. “nick.c” DeMello <editor@mactecb.com> 


I generally don’t like surprises. I browse the last chapter of 
novels, I peak at Christmas presents, and I stay away from 
Stephen King movies. 1 like to know what’s coming. 

With Apple, knowing what’s coming hasn’t always been that 
easy. They’ll send you a Christmas card promising one present, but 
when you get the package (in June) you find something entirely 
different under the wrapping paper. To be fair, die computer 
industry as a whole changes constandy and is about as predictable 
as a cat’s tail. We all (even Apple) need to adapt to those changes 
and rechart our plans accordingly. I’ve certainly delivered more diat 
one project a little behind schedule, and a little different than the 
draft spec — so I can’t cast any stones. But it sure can lx? frustrating 
when you’re trying to make long term plans your software. 

Well, that’s been the case. 

Something odd happened this year. Apple turned off their 
hype machine and dug in hard. Not only did they make very 
few promises, but they did their best to be sure we couldn’t 
even peak over their shoulder (so those of us in the press 
couldn’t make any promises for Apple either :-). Then 
products started coming out. 

Mac OS 8.1 was a good incremental release. Not flashy, but 
solid — which is what you want from a x.l release, 'then, on the 
last day of the last month of Q1 Apple released QuickTime 3.0, an 
incredibly feature rich new release of the Apple’s jx)werful 
multimedia architecture. Next we heard that G3 PowerBooks and 
Rhapsody DR2 would be coming our way in Q2 (which 1 personally 
interpreted to mean I’d be able to actually buy a G3 PowerBook for 
Christmas). Christmas came early. Folks had the incredibly sexy new 
PowerBooks at WWDC in May and a Rhapsody CD to put into them. 
It took another month IxTore 1 was able to pick up a G3 PowerFkx)k 
at my favorite hardware outlet. But, that was still in Q2 and the 
hardware wasn’t just “released” — it was available. 

Apple told us that we’d be seeing more new products in 
Q3: the iMac, Mac OS 8.5 (AKA Allegro), Mac OS Server (nee 
Rhapsody), and a dramatically improved MRJ 2.1 (with Java 1.1.6 
and swing). This time I wasn’t sure what to think, so 1 waited 
and tried my best to be patient. Sure enough, iMac is here and 
it seems to be taking the consumer market by storm. It looks to 
me like 8.5 may be ready by the time this column is printed. Still, 
that leaves the Mac OS Server and the new MRJ (to be fair 
though, Steve did say that we were looking at the new JVM in 
“the Allegro time frame” — so I can see this coming in Q4). 

Oh, and somewhere along the way the hype machine came 
back online. There was a subtle difference though. Instead, of 
telling us how revolutionary OpenDoc was going to be or how 
powerful Rhapsody would be, that hype machine was talking 
about delivered products and available technologies. Simple, 
clear, and effective messages about why folks should buy 


Macintosh G3s or why developers should use QuickTime. It still 
had all the subtlety of a hammer throw or a steam roller, but it 
also had the Byte marks (on shipping products) and technology 
demos to back up those insanely great claims. 

Say what you will about the mistakes Apple has made in the 
past The simple truth is, in 1998 Apple delivered. More importantly, 
they established a strong foundation for next years technologies. 
Rhapsody and the Carlxrn protocols make Mac OS X a very 
believable goal, and after the iMac and G3 PowerBooks I’m Imking 
forward to what Steve has in line for ihe Consumer Portable. 

I don’t know that in 1999 Apple will stick to the new motto 
Steve seems to have borrowed (“Just do it.”). But, to borrow 
another motto, “I want to believe,” and Apple is making it a lot 
easier to do so these days. 
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GETTING 

STARTED 


by Dave Mark and Dan Parks Sydow 


Apple Events 


How a Mac program handles Apple events 


An Apple event is a high-level event that allows a program 
to communicate with another program, with the Finder, or even 
with itself. The program that issues the Apple event is referred to 
as the client application, while the program that receives and 
responds to the event is called the server application. Apple 
events are especially important when the Finder needs to 
communicate with a program. For instance, when the user opens 
a document by dragging its icon onto the icon of the application 
that created it, an Apple event is involved. In such a case the 
Finder launches the application (if it’s not already running) and 
then sends an Open Document Apple event to the program to tell 
the program to open the dragged document. In this type of 
communication the Finder is the client and the application is the 
server. This month, we’ll look at how Apple events make this type 
of common and important Finder-application communication 
possible. And, of course, we’ll look at how you can incorporate 
this behavior into your own Mac applications. 

The Required Apple Events 

In the very old days (were talking pre-System 7 here), when a 
user double-clicked on a document the Finder first looked up the 
document’s creator and type in its desktop database to figure out 
which application to launch. It then packaged information about 
the document (or set of documents if the user double-clicked on 
more than one) in a data structure, launched the appropriate 
application, and passed the data structure to the application. To 
access this data structure, the application called the routine 
CountAppFiles() (to find out how many documents it needs to 
open or print) then, for each one, it called GetAppFiles() (to gel 
the information necessary to open the file) and either opened or 
printed the file. This model is no longer supported — it’s been 
out of date for quite a while. In System 7, and now Mac OS 8, 
when a user opens a document the Finder still uses the file’s 
creator and type to l<x:ate the right application to launch. Once 
the application is launched, however, things differ. Now, the 
Finder sends the program a series of Apple events. 

• If the application was launched by itself, with no 
documents, the Finder sends it an Open Application Apple 


event. This tells the application to do its standard 
initialization and assume that no documents were opened. 
In response to an Open Application Apple event, the 
application will usually (but not necessarily) create a new, 
untitled document. 

• If a document or set of documents were used to launch the 
application, the Finder packages descriptions of the 
documents in a data structure known as a descriptor, adds 
the descriptor to an Open Document Apple event, then 
sends the event to the application. When the application 
gets an Open Document event, it pulls the list of documents 
from the event and opens each document. 

• If the user asked the Finder to print, rather than open, a 
document or set of documents, the Finder sends a Print 
Document Apple event instead of an Open Document event. 
The same descriptor procedure as used for an Open 
Document Apple event is followed, but in response to a 
Print Document Apple event the application prints rather 
than opens the document. 

• Finally, if the Finder wants an application to quit (perhaps 
the user selected Shut Down from the Special menu) it sends 
the application a Quit Application Apple event. When the 
application gets a Quit Application event, it does whatever 
housekeeping it needs to do in preparation for quitting, then 
sets the global flag lhal allows it to drop out of the main 
event loop and exit. 

These events are the four required Apple events. As the name 
implies, your application is expected to handle these events. For 
brevity, and to isolate individual programming topics, previous 
Getting Started examples didn’t include Apple event code. 'I'o be 
considered a user-friendly, well-behaved program, your full- 
featured Mac application must handle these events. 

There are a couple of other situations besides the above- 
mentioned scenarios where your application might receive one 
of the required Apple events. For starters, any application can 
package and send an Apple event. If you own a copy of CE 
Software’s QuicKeys, you’ve got everything you need to build 
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and send Apple events. If you have the AppleScript extension 
installed on your Mac, you can use Apple’s Script Editor 
application to write scripts that get translated into Apple events. 
If you make your application recordable (so that the user can 
record your application’s actions using the Script Editor, or any 
other Apple event recording application) you’ll wrap all of your 
program’s actions in individual Apple events. This means that 
when the user selects Open from the File menu, you’ll send 
yourself an Open Document Apple event. If the user quits, you’ll 
send yourself a Quit Application event. 

In addition to the events described above, there are other 
situations in which the Finder will send you one of the four 
required Apple events. If the user double-clicks on (or otherwise 
opens) one of your application’s documents, the Finder will 
package the document in an Open Document Apple event and 
send the event to your application. The same is true for the Print 
Document Apple event. 

The user can also drag a document onto your application’s 
icon. If your application is set up to handle that type of 
document, your application’s icon will invert and, when the user 
releases the mouse button, the Finder will embed the document 
in an Open Document Apple event and send the event to your 
application. Note that this technique can be used to launch your 
application or to request that your application open a document 
once it is already running. 

Apple Event Handlers 

Apple events are placed in an event queue, much like the 
events you already know, love, and process, such as 
mouseDown, activateEvt, and updateEvt. So far, the events you’ve 
been handling have all been low-level events — the direct result 
of a user’s actions. The user uncovers a portion of a window, an 
updateEvt is generated. The user clicks the mouse button, a 
mouseDown is generated. Apple events, on the other hand, are 
known as high-level events — the result of interprocess 
communication instead of user-process communication. As you 
process events retrieved by WaitNextEvent(), you’ll take action 
based on the value in the event’s what field. If the what field 
contains the constant updateEvt, you’ll call your update handling 
routine, etc. If the what field contains the constant 
kHighLevelEvent, you’ll pass the event to the routine 
AEProcessAppleEvent(). Here’s a typical event-handling routine 
that supports Apple events: 

voidDoEvent( EventRecord *eventPtr ) 

( 

char T.heChar; 

switch ( eventPtr >what ) 

( 

case mouseDown: 

HandleMouseDovn( eventPtr ); 
break: 

case keyDown: 

case autoKey: 

thcChar " eventPtr->message & charCodeMask; 
if ( (eventPtr >modtfiers & cmdKey) != 0 ) 
IlandleMenuChoice( McnuKey( theChar ) ); 
break: 


case updateEvt: 

DoUpdate( eventPtr ); 
break: 

case kHighLevelEvent: 

AEProcessAppleEvent( eventPtr ): 
break; 

1 

) 

AEProcessAppleEventQ is a powerful routine whose 
purpose is to identify the type of Apple event that is to be 
processed, and to begin processing that event by passing the 
event to an Apple event handler. An Apple event handler is 
a routine you’ve written specifically to handle one type of 
Apple event. If your program supports the four required 
Apple event types, you’ll be writing four Apple event handler 
routines. This month’s example program provides an 
example of each of these handlers. 

Writing an Apple event handler isn’t enough — you also 
need to install it. You install a handler by passing its address (in 
the form of a universal procedure pointer, or UPP) to the Toolbox 
routine AEInstallEventHandler(). This installation takes place early 
in your program — typically just after Toolbox initialization and 
the setting up of your program’s menu bar. Once the handlers are 
installed, your work is done — when your program receives an 
Apple event the call to AEProcessAppleEvent() automatically calls 
the appropriate handler. 

AEHandler 

This month’s example program, AEHandler, can be 
launched like any other Mac application: by double-clicking 
on its icon. When launched in this way the program does 
nothing more than display an empty window. AEHandler can 
also be launched by dragging and dropping an AEHandler file 
onto the application icon. Using this second program-starting 
method opens the dropped file. Dragging and dropping a file 
on the application icon of the already-running AEHandler 
program also results in the file being opened. And unlike a 
program that doesn’t support the required Apple events, 
AEHandler knows how to quit itself when Shut Down is 
selected from the desktop’s Special menu. 

When you run AEHandler you’ll note that there’s not 
much to see. For the example program we aren’t interested 
in a fancy interface, though — so you aren’t getting 
shortchanged. What AEHandler is doing behind the scenes is 
far more interesting: Apple events are responsible for all 
above-mentioned features. This month’s program, then, 
serves as a skeleton you can use to add the required Apple 
events to your own programs. 

Creating the AEHandler Resources 

Start off by creating a folder called AEHandler in your 
development folder. Launch ResF.dit and create a new File called 
AEHandler.rsrc in the AEHandler folder. Create the menu-related 
resources — by now you should be used to creating menu bar 
and menu resources. The MBAR resource has an ID of 128, and 
it references the three MENU resources shown in Figure 1. 
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Figure 1. The three MENUs used by AEHandler. 

Now create a WIND resource with an ID of 128. The 
coordinates of the window aren't critical — we used a top of 50, 
a left of 10, a bottom of 100, and a right of 310. Use the standard 
document proc (leftmost in a RcsEdit editing pane). 

The AEHandler program includes some error-checking 
code. Should a problem arise, the program posts an alert that 
holds a message descriptive of the problem. This alert is defined 
by an ALRT with an ID of 128, a top of 40, left of 40, bottom of 
155, and right of 335. Next, create a corresponding DITL with an 
ID of 128 and two items. Item 1 is an OK button with a top of 
85, a left of 220, a bottom of 105, and a right of 280. Item 2 is a 
static text item just like the one shown in Figure 2. Make sure 
to include the caret and zero characters in the Text field. 


□ Edit DITL item #2 from REHandler.rsrc E 

TGHt: ~B 
1 Static Te~Ht ▼) 


□ Enabled Top: |l8 | Height: 170 

Left: 165 | Width: |?8B 


Figure 2. The static text item for the error alert. 

That covers the standard resources. Next come the 
resources that link specific document types to our application 
and that lie a set of small and large icons to our application. The 
Finder uses these resources to display an icon that represents 
our application in different situations (a large icon when the app 
is on the desktop, a small icon to display in the right-most corner 
of the menu bar when our app is front-most). The Finder uses 
the non-icon resources to update its desktop database. 

Create a new BNDL resource with a resource ID of 128. 
When the BNDL editing window appears in ResEdit, select 
Extended View from the BNDL menu. This gives you access to 
some additional fields. Put your application’s four-byte signature 
in the Signature field. Every time you create a new application, 
you’ll have to come up with a four-character string unique to 
your application. To verify that the signature is unique, you’ll 
need to send it to Apple at their Creator/File Type Registration 
web site (http://developer.apple.com/dev/cftype/). If you don’t have a 
signature handy, and don’t feel like going online to find an 
unused one to register, feel free to temporarily use one of ours 
for now. The signature ‘DMDS’ is one w r e’ve registered, but don’t 
(and won’t) use for any distributed application — so you won’t 
run into any conflicts with other programs on your Mac. 


Now fill in the remaining two fields near the top of the 
BNDL resource. As shown in Figure 3. the ID is set to 0 and the 
© String field holds a copyright string that will appear in the 
Finder’s Get Info window for your application. 

Z BNDL 10 * 128 from RFHamJler.rxn 


Signature: |0MDS | 

ID: |B | (should be B) 

© String: Resting the require d Hpple euen ts. ~| 


FREF 
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local 

res ID 

ICN* icW icl8 ics*ics4ics8 


0 

128 

flPPL 

B 

128 

ihibih™ 


' 

129 

TEHT 

1 

129 

liiooB 


2 

130 

???? 

2 

B 




Figure 3. The AEHandler BNDL resource. 


Finish off the BNDL resource by adding information alx)ut 
each type of file that the Finder should associate with the 
AEHandler program. Select New File Type from the Resource 
menu. Use the specifications in Figure 3 to fill out the 
information for the APPL file type. This ties the first row of icons 
to the application itself. To edit the icons, double-click on the 
icon area and ResEdit will open an icon family editing window. 

Back in the BNDL editing window, select New File Type 
again to add a second row of file types to the BNDL window. 
This time use the specs in Figure 3 to fill out the info for files of 
type TEXT. By doing this, we’ve told the finder that files with the 
signature ‘DMDS' and of type ‘TEXT’ belong to the application 
AEHandler. Once again, double-click on the icon family to edit 
the individual icons. 

If your application will support file types belonging to other 
applications, create file type entries in the BNDL resource for 
them as well, but don’t edit the icons — leave them blank. 

Finally, be aware that the Finder uses the file type entries to 
determine what files can drop launch your application. Right 
now, the Finder will only let you drop-launch files with the 
signature ‘DMDS’ and of type TEXT’ on AEHandler. To make 
AEHandler respond to all file types, create a new file type entry 
with the file type '****’. Don’t edit the icons — leave them blank. 

That’s it for the AEHandler.rsrc file — but not for ResEdit. Save 
your changes to AEHandler.rsrc and close the resource file. While 
still in ResEdit, create a new resource file called test.text. Select Get 
Info for test.text from ResEdit’s File menu. When the info window 
appears, set the file’s type to TEXT and its creator to whatever 
signature you used (if you used ours, it’s DMDS). That’s it. Save 
your changes, quit ResEdit, and get set to create the project. 

Creating the AEHandler Project 

Launch CodeWarrior and create a new project based on die 
MacOS:C_C-H-:MacOSToolbox:MacOS Toolbox Multi-Target stationary. 
Uncheck the Create Folder check box. Name the project 
AEHandler.mcp and specify that the project lx.* placed in the 
AEHandler folder. Immediately edit the creator information in the 
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Stufftt instaleifflaker is 
so simple to use, 
it’s easy to overlook 
just how deep it is. 


Now with support for hierarchical packages and sublevel assignments. 

Stufflt InstallerMaker has long been hailed as the painfree way to create custom installers for your 
software. Now the installer that’s the easiest to use is also more robust! InstallerMaker 5.0 has the 
features more developers want, including support for hierarchical packages and sublevel assign¬ 
ments of conditions, actions and packages to nested child items. This allows for the creation of complex 
installers for developers of large, high-end applications. All without sacrificing an ounce of InstallerMaker’s 
famous ease-of-use. InstallerMaker 5.0 also lets you build installers that retrieve files directly off HTTP or 
FTP sites. Completely Mac OS 8 compatible, InstallerMaker 5.0 is loaded with a bunch of cool features that 
make it the preferred choice of more developers, 

ISP’s and IS professionals. Download a free, fully- STl[\!VjlI I [II) II il/UI) ^ || 

functional copy from www.aladdinsys.com, or call Ullllij I 11JIJ It IL! I 11\ Ij ll 

(408) 761-6200 and ask for Developer Sales. The Complete Data Distribution Solution 

‘The main tiling 1 like about Aladdin’s Stufflt InstallerMaker is that, it’s as easy to use as Stufflt Deluxe. It lets me concentrate on more important things than writ¬ 
ing installers.” Steve Domer, VP of Technology, Qualcomm 

“Stufflt InstallerMaker is an indispensable tool for our software distribution and system administration needs. InstallerMaker makes it easy for us to create robust, 
portable, flexible and bulletproof installers, and it’s getting better!” Steve Hideg, Macintosh administrator and consultant, University of Notre Dame 

Check out the latest features of Stufflt. InstallerMaker 5.0: 

• Support for Hierarchical Packages • Total OS 8 Compatibility • Best. Compression Available • Still the easiest to use! 

and Sublevel Assignments • Custom Destinations • Resource Installation 

• Installation from HTTP or FTP sites • Shrinkwrap • Scripting and Recording 

• Electronic Transaction Processing • Install or Uninstall • Built-In “Smart" Updaters 

_ Aladdin 

Tm Systems 

If coding was meant to be perfect the first lime, 
everything would be numbered point zero. 

That’s why you need to track each build. Sometimes good 
code goes bad. FlashBack gives you unlimited undos which 
allow you to track and control every version of your build. It 
works with virtually any program, automatically in the back¬ 
ground. Use FlashBack lor all your projects. Because some¬ 
times it’s better to go back than to plow ahead. Visit 


www.aladdinsys.com/flashback to find out more about 
FlashBack, or visit your favorite reseller. 

Aladdin 

FlashBacK 

Add Unlimited Undos to all Your Software 
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target panel of the project settings dialog box (select the project 
settings item from the Edit menu, click on 68K Target or RFC 'target 
in the scrollable list, and then type the four-character creator code 
in the Creator edit box). Set the project’s creator to the creator you 
used (‘DMDS’ if you’ve followed our suggestion). Next, be sure that 
the isHighhevelEventAware flag is set in the ‘SIZE’ Flags popup 
menu. By default it should be. If it isn’t, select it — if it’s not set, 
the Apple Event Manager toon’t call your handler s! 

Remove the SillyBalls.c and SillyBalls.rsrc files from, and add 
the AEHandler.rsrc file to, the project. This project doesn’t make 
use of any of the standard ANSI libraries, so feel free to clean up 
the project window by removing the ANSI Libraries folder. 

Next, choose New from the File menu to create a new source 
code window. Save it with the name AEHandler.c, then add the 
new file to the project by choosing Add Window from the Project 
menu. The entire AEHandler source code listing can be found in 
the source code walk-through. You can type it into the 
AEHandler.c file as you read the walk-through, or you can save a 
lot of effort by just downloading the whole project from 
MacTech’s ftp site <ftp://ftp.mactech.com/src/>. 


Walking Through the Source Code 

The AEHandler source code listing begins with a number 
of #defines — most of which you’ll be familiar with from 
previous examples. 


^********************* *********************J 

//define kBaseResID 128 

//define kALRTResID 128 

//define kWINDResID 128 


//define kSleep 
//define kMoveToFront 
//define kGestaltMask 
//define kAetivate 
//define kVisible 
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(WindowPtr) - 1L 
1L 

false 

true 


//define kWindowStartX 20 
//define kWindowStartY 50 


pascal OSErr DoOpenDoc( AppleEvent *event, AppleEvent * reply, 
long refcon ); 

pascal OSErr DoPrintDoc(AppIeEvent ‘event, AppleEvent *reply, 
long refcon ); 

pascal OSErr DoQuitApp( AppleEvent *event, AppleEvent * reply, 
long refcon ); 

void OpenDocument( FSSpec *fileSpecPtr ); 

WindowPtr CreateWindow( Str255 name ); 

void DoError( Str255 errorString ); 

void EventLoop( void ); 

void DoEventC EventRecord *eventPtr ); 

void HandleMouseDown( EventRecord ‘eventPtr ); 

void HandleMenuChoice( long menuChoice ); 

void HandleAppleChoice( short item ); 

void HandleFileChoice( short item ); 

void DoUpdate( EventRecord ‘eventPtr ); 

void DoCloseWindow( WindowPtr window ); 


The main() routine does its usual work, but here it also 
initializes Apple events before entering the main event loop. 

j*******M**t*t**±*t*X*4.* * * 4 * * * *** *** * .* * * * ****** j 

void main ( void ) 

{ 

Toolboxlnit(); 

MenuBarlnit(); 

AEInitO ; 

EventLoopO : 

1 


I******************** 'pooiUoxInit ******************** j 

void Toolboxlnit( void ) 

( 

InitGraf( &qd.thePort ); 
InitFonts(); 

InitWindows(); 

InitMenus(); 

TEInit{); 

InitDialogs( 0L ); 

InitCursor(); 


j******************** MenuBiirInit ******************** f 

void MenuBarlnit( void ) 

{ 

Handle menuBar; 

MenuHandle menu; 


//define mApple kBaseResID 

//define iAbout 1 


menuBar = GetNewMBar( kBaseResID ); 
SetMenuBar( menuBar ); 


//define mFile 
//define iClose 
//define iQuit 


kBaseResID+1 

1 

3 


menu = GetMenuHandle( mApple ); 
AddRcsMcnu( menu, ‘DRVR’ ); 

DrawMenuBar(); 


As always, the global variable gDone indicates when it’s time 
to exit the main event loop. Variables gNewWindowX and 
gNewWindowY serve as offsets to stagger open windows. And of 
course each application-defined function has its own prototype. 

****04**************** oI/xKqIc *%*%*%*%%**%%***%***** I 


Boolean 

gDone; 

short 

gNewWindowX = kWindowStartX, 
gNewWindowY = kWindowStartY; 

/*************** 

****** functions ******«*************/ 

void 

ToolBoxInit( void ); 

void 

MenuBarlnit( void ); 

void 

AEInit( void ); 

void 

AEInstallHandlers( void ); 


pascal OSErr DoOpenApp( AppleEvent ‘event, AppleEvent ‘reply, 
long refcon ); 


The Apple-defined constant gestaitAppleEventsAttr is a 
selector code that tells the Toolbox function Gestalt() to return 
information about the availability of Apple events on the user’s 
machine. If Gestalt() fills feature with the Apple-defined constant 
gestaltAppleEventsPresent, then we know it’s okay to include 
Apple event code in our program. If there’s an error along the 
way, we call our own DoError() routine (discussed later) to clue 
the user in to the problem. AEInit() ends with a call to 
AEInstallHandler(), which is described next. 

!****************%***** *********************** j 

voidAEInit( void ) 

{ 

OSErr err; 
long feature; 
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err =• Cestalt! gestaltAppleEventsAttr. ^feature ); 
if ( err !• noErr ) 

DoError( “\pError returned by Gestalt!” ); 

if ( ! ( feature & ( kGestaltMask « 

gestaltAppleEventsPresent ) ) ) 
DoError( "\pThis Mac docs not support Apple events..." ): 

AEInstallHandiersO : 


Each Apple event handler needs to be installed. Looking at 
how that is done for one handler provides you with enough 
information to see how any handler is installed. Let’s look at how 
our AEInstallHandiersO function installs the handler routine that’s 
to process Open Application Apple events. 

A call to tlie Toolbox routine AEInstallEventHandler() is made to 
specify that the application-defined routine DoOpenApp() (covered 
ahead) is the handler for Open Application events. The first 
argument to AEInstallEventHandler(). kCoreEventClass, defines the 
event class of die event to be handled. All four of the required Apple 
events are considered core events. The second argument, 
kAEOpenApplication, is an Apple-defined event ID that specifies 
which particular Apple event is to be handled. The third argument is 
a pointer to the application-defined function that is to handle this one 
type of Apple event. When passed a function name, die Toolbox 
function NewAEEventHandlerProc() returns the needed pointer. Tlie 
fourth argument, OL, is a reference value diat the Apple Event 
Manager uses each time it invokes the event handler function. You 
can safely us a value of 0 here. The final argument is a Boolean value 
that specifies in which Apple event dispatch table (die means of 
correlating an Apple event with a handler) the handler should l>e 
added. A value of false here tells the Apple Event Manager to add die 
event handler to die application’s own dispatch table as opposed to 
adding it to die system dispatch table (a table that holds handlers 
available to all applications). Should the call to AEInstallEventHandler() 
fail for any reason, we call our DoError() routine (discussed ahead), 
specifying which Apple event type was the source of the failure. 

r^**** 4 "*" AEInstallHandlcrs 

void AElnstallHandlers( void ) 

( 

OSErr err: 

err - AEInstallEventHandier( kCoreEventClass, 
kAEOpenApplication. 

NewAERvent.HandlerProc( DoOpenApp ), OL, false ): 

if ! err !■ noErr ) 

DoError( "\pError installing Open App handler..." ): 

err = AEInstallEventHandier! kCoreEventClass, 
kAEOpenDocuments, 

NewAEEventHandlerProc! DoOpenDoc ), OL. false ); 

if ( err != noErr ) 

DoError! “\pError installing Open Doc handler...” ); 

err = AEInstallEventHandier( kCoreEventClass, 
kAEFrintDocuments, 

NewAEEventHandlerProc! DoPrintDoc ), OL. false ): 

if ( err !• noErr ) 

DoError! "\pError installing Print Doc handler..." ); 

err - AEInstallEventHandier! kCoreEventClass, 
kAEQuitApplication, 

NewAEEventHandlerProc! DoQuitApp ), OL, false ); 

if ( err != noErr ) 

DoError! "\pError installing Quit App handler..." ); 

} 


An Apple event handier has a clearly defined purpose. It 
extracts data from the Apple event, handles the specific action 
that the event requests, and returns an error result code to 
indicate whether or not die event was successfully handled. How 
the functionality of the event handler routine is implemented is 
up to you. Each handler has the same general format: it starts with 
the pascal keyword, has a return type of OSErr, and includes three 
parameters. The first parameter holds the Apple event to handle. 
Ihe second parameter is available to hold information that might 
need to be returned to AEProcessAppleEvent() (recall that this is 
the routine that invokes the handler). 'Ihe final parameter is a 
reference value that your application will typically ignore. 
DoOpenApp(), which is the event handler for an Open Application 
Apple event, provides an example: 

DoOpenApp *««"**""*«*—*-/ 

pascal OSErr DoOpenApp! AppleEvent ‘event, AppleEvent ‘reply, 
long refcon ) 

I 

OpenDocument( nil ); 
return noErr; 

1 


DoOpenApp() is invoked when the AEHandler application is 
launched. We’ve opted to have the program open a new window 
at startup. The application-defined routine OpenDocument() takes 
care of that task. Later we mention how OpenDocument() works, 
but there’s no need to gel into the nitty-gritty. The point has been 
made: the body of an event handler simply holds the typical Mac 
code that is needed to solve the task at hand. Once you know 
the format of an event handler, writing the routine itself is no 
different than writing any other function. 

Some event handlers are easier to write than others. 
Consider our example program’s handler for a Print Document 
Apple event: 

DoPrintDoc •**»*****•***••*•*••*•/ 


pascal OSErr 
l 


DoPrintDoc(AppleEvent ‘event, 
long refcon ) 


return noErr; 

) 


AppleEvent ‘reply. 


The AEHandler program doesn’t support printing, so we’ve 
defined the DoPrintDoc() function to do nothing more than 
return. So while the program technically does handle a Print 
Document Apple event, the effect is that the event is ignored. 
Before you cry “foul!”, keep in mind that we haven’t discussed 
the topic of printing in Getting Started — so we really can’t 
venture off down that road just yet. At least now our application 
can be considered set up and ready to respond to printing 
requests from the Finder. Should we get into printing in the 
future (and if demand warrants it, of course we will), we can 
add the printing code in the DoPrlntDoc() routine. 

A Quit Application Apple event is simple to handle — all we 
need to do is set the global variable gDone to true. Ihe 
AEHandler version of this handler also beeps to let you know 
that it was an Apple event rather than the Quit menu item that 
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caused the application to quit — your application’s version of 
this handler won’t need the call to SysBeep(). 

DoQuitApp 

pascal OSF.rr DoQuilApp( AppleEvent 'event, AppleEvent 'reply, 
long refcon ) 

{ 

SysBeep( 10 ): 
gDone * true; 

return noErr; 

) 

Finally, it’s on to a handler that has a little substance to it. 
If the user drops an AEHandler file onto the AEHandler icon 
in the Finder, then the AEHandler application receives an 
Open Document Apple event. Some Apple events are 
composed of parameters — records which contain information 
to be used by the receiving application. An event’s direct 
parameter is the one that the receiving application is to act 
upon. For the Open Document event, the direct parameter is 
a descriptor list of the files that are to be opened. A call to 
AEGetParamDesc() delivers that list to the handler. Here we’re 
saving the list to the local variable docList: 

err = AEGetParamDesc( event, keyDirectObject. typeAEList, 
&docList); 


Next, we determine the number of entries in the list so that 
we know how many files are to be opened: 

err = AECountltems( &docList, knumDocs ); 

A for loop opens each file in turn. A call to AEGetNthPtr() 
returns one item from the list. We do a little finagling to make 
sure that the returned item is received in the form of a file system 
specification, or FSSpec. The application-defined routine 
OpenDocument() does the actual opening of Lhe file. 

for ( i-1; i<=numDocs; i++ ) 

I 

err - AEGctNthPtr( &docList, i, typeESS. &keywd, 

&returnedType. (Ptr)&fileSpec. 
sizeof( fileSpec ). &actualSize ); 

OpenDocument( &fileSpec ); 

I 

Calling AEGetParamDesc() resulted in the Apple Event Manager 
creating a copy of lhe descriptor list for the program’s use. We’re 
done with that copy, so we’ll deallocate the memory it occupied: 

err “ AEDisposeDesc( kdocList ); 

We’ve just covered it piecemeal, now here’s the 
DoOpenDoc() function in its entirety: 

yMMIMMWIMMW DoOpOlDOC .'/ 

pascal OSErr Do0pcnDoc( AppleEvent 'event, AppleEvent 'reply, 
long refcon ) 

l 

OSErr err; 

FSSpec fileSpec; 

long i, numDocs; 

DescType returnedType; 

AEKeyword keywd; 

Size actualSize; 


AEDescList docList = l typeNul1, nil ); 

err = AEGetParamDesc( event, keyDirectObject, 
typeAEList, &docList); 

err = AECountltems( WocList, &numDocs ); 

for ( i=l; i<=numDocs; i++ ) 

{ 

err = AEGetNthPtr( &docList, i. typeFSS, fckeywd, 
^returnedType. (Ptr)&fileSpec, 
sizeof( fileSpec ). fcactualSize ): 

OpenDocument( &fileSpec ); 

) 

err = AEDisposeDesc ( &docList. ); 
return err; 

1 

OpenDocument() selects an appropriate title for the about-to- 
be-opened window, then calls the application-defined routine 
CreateWindow() to actually create and display the new window. 

OpenDocument 

void OpenDocument( FSSpec ‘fileSpecPtr ) 

I 

Wind owP t r wind ow; 

if ( fileSpecPtr = nil ) 

window = CreateWi.ndow( "\p<Untitled>” ); 
else 

window = CreateWindow( fileSpecPtr->name ): 

} 

CreateWindow() opens a new window based on AEHandler’s 
one WIND resource, sets the window’s title, then offsets the 
window from the last-opened window. The bulk of 
CreateWindowQ is code for staggering the new window. The 
newly opened window will lx.* empty — regardless of the 
contents of the file that’s being opened. The code necessary to 
read the contents of the file and then display that information in 
a window is dependent on what your application does. 

C reateWindow “““""*"*“**“‘7 

WindowPtrCreateWindow( Str255 name ) 

( 

WindowPtrwindow; 

short windowWidth, windowHeight; 

window = GetNewWindow( kWTNDRcsID, nil, kMoveToFront ); 

SetWTitle( window, name ); 

MoveWindow( window, gNewWindowX, gNewWindowY, kActivate ); 
gNewWindowX += 20; 

windowWidth = window->portRcct.right 

window >portRect.left; 

if ( gNewWindowX + windowWidth > 

qd.screenBits.bounds.right ) 

I 

gNewWindowX = kWindowStart.X; 
gNewWindowY = kWindowStartY; 

1 

gNewWindowY += 20; 

windowHeight = window->portRect.bottom - 
window->portRect.top; 

if ( gNewWindowY + windowHeight > 

qd.screenBits.bounds.bottom ) 
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( 


gNewWindowX = kWindowStartX; 
gNewWindowY = kWindowStartY; 


ShowWindow( window ); 
SetPort( window ); 

return window; 


If AEHandler encounters an error, it posts an alert that 
provides some error-specific information to help the user 
determine what went wrong. The DoError() routine displays this 
alert, then terminates the program. The Toolbox function 
ParamTextO displays up to four strings in an alert — the routine 
looks for occurrences of the strings “AO”, “Al", “A2”, and “A 3 ” i n 
any static text items in the frontmost alert or dialog lx>x and 
replaces each with the four strings that were passed to ParamText(). 
In DoError() we only pass one string (the tliree “\p" values each 
representing empty strings) — the string received in the errorString 
parameter to DoError(). Refer back to Figure 2 to see how this 
string will appear in the alert displayed by the subsequent call to 
StopAlert(). Including a DoError()-type routine in a program is a 
simple and effective way to handle errors — consider 
incorporating such a function in any Mac program you write. 


void DoError( Str255 errorString ) 

( 

ParamText( errorString, “\p", “\p’\ "\p" ); 
StopAlert( kALRTResID, nil ): 

ExitToShell(); 

1 


The rest of the code takes care of event-handling, and 
should look quite familiar to you. That means we can dispense 
with the walk-through of it. Refer back to recent Getting Started 
columns for more information on event-handling. 


* EvcniLoop 


7 


void EventLoop( void ) 
{ 

EventRecord event; 


gDone “ false; 

while ( gDone = false ) 

( 

if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) ) 
DoEvent( &event ); 

) 


/—•*“-**♦****•**** DoEvent . mmm—— « / 

void DoEvent( EventRecord *eventPtr ) 

{ 

char theChar; 

switch ( cventPlr >whal ) 

( 

case mouseDown: 

HandleMouseDown( eventPtr ); 
break; 

case keyDown: 
case autoKey: 

theChar • eventPir >message & charCodeMask; 
if ( (eventPtr >modifiers & cmdKey) != 0 ) 
HandleMenuChoice( MenuKey( theChar ) ); 


“More than a decade 
of itlacTech on CD!” 

The MacTech CD represents the definitive 
reference for Macintosh programmers. 
MacTech’sTHINK Reference viewer is a 
sophisticated database search engine that 
allows you to navigate through almost a 
decade and a half of MacTech articles. 

This complete history of MacTech 
Magazine contains content illustrating 
how to accomplish some of the most 
fundamental as well as most advanced 
aspects of programming the Macintosh. 



In addition to the MacTech Magazine data¬ 
bases, the CD also includes the entire rim 
of Apple’s develop Magazine. These 29 
issues of articles on Apple tedinology, often 
written by the same engineers who created 
that tedinology, are compiled into compact 
THINK Reference viewer databases. More 
THINK Reference databases include Apple’s 
classic Inside Macintosh technical manuals 
- the definitive reference to the Mac 
Toolbox - and the largest collection of 
Frameworks articles available. 

For more information see 

<http://www.mactech.com> 
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break; 

case updateEvt: 

DolJpdate( eventPtr ); 
break; 

case kllighLcvclEvent: 

AEProcessAppleEvent( eventPtr ); 
break; 



/************"*** HandleMouscDown . ."7 

void liandleMouseDown( EventRecord *eventPtr ) 

{ 

WindowPtrwindow; 
short thePart; 

long menuChoice; 

thePart = FindWindowC eventPtr->where, fcwindow ); 
switch ( thePart ) 

{ 

case inMenuBar: 

menuChoice = MenuSelect( eventPtr >where ); 

HandieMenuChoice( menuChoice ); 

break; 

case inSysWindow ; 

SystemClick( eventPtr, window ); 
break; 

case inGoAway: 

if ( TrackGoAway( window. eventPtr->where ) ) 
DoCloseWindow( window ); 
break: 

case inContent: 

SelectWindow( window ); 
break; 

case inOrag : 

DragWindow( window, eventPtr >where, 

&qd.screenBits.bounds ): 

break; 

) 

) 


^***************** HandleMenuChoice •*«**•**««*««/ 

void HandleMenuChoice( long menuChoice ) 

{ 

short menu; 
short item; 
if ( menuChoice !■ 0 ) 

( 

menu = HiWord( menuChoice ): 
item * LoWord( menuChoice ); 
switch ( menu ) 
i 

case mApple: 

HandleAppleChoice( item ); 
break; 
case mfile: 

liandleFileChoice( item ); 
break; 

) 

HiliteMenu( 0 ); 

} 

) 


/***♦♦**♦*"***•* HandlcAppleChoice *****************7 

void HandleAppleChoice( short item ) 

( 

MenuHandle appleMenu; 

Str255 accName; 
short accNumber: 
switch ( item ) 

I 

case iAbout: 

SysBeep( 20 ): 
break; 
default: 

appleMenu • Get.MHandle( mApple ); 
Gctltcm( appleMenu, item, accName ); 
accNumber = OpcnDeskAcc( accName ); 
break; 


/»««„«««,« HandlcFilcChoicc 

void HandleFileChoice( short item ) 

I 

switch ( item ) 

{ 

case iClose: 

DoCloseWindow( FrontWindowO ); 
break; 
case iQuit: 
gDone = true: 
break; 

1 


^, M «*****w***«** DoUpdatC 7 

void DoUpdate( EventRecord *eventPtr ) 

{ 

WindowPtrwindow; 

window = (WindowPtr)eventPtr*>message; 

BeginUpdate(window); 

EndUpdate(window); 


DoClosc Window 


V 


void DoCloseWindow( WindowPtr window ) 

I 

if ( window != nil ) 

DisposeWindow( window ); 

1 


Running AJEIIandeer 

Save your code, then choose Run from CodeWarrior’s 
Project menu to build and then run the AEHandler application. 
An untitled window should appear. If it didn’t, go back and 
check your SIZE resource to make sure the High-Level-Event 
Aware flag is set. 

As you look through the code, you’ll see that the untitled 
window is created by the Open Application handler. Now double 
click on the file test.text. A window titled test.text should appear. 
This window was created by the Open Documents handler. 

With AEHandler still running, go into the Finder and select 
Shut Down from the Special menu. The Finder should bring 
AEHandler to the front and send it a Quit Application Apple 
event. Our Quit Application handler beeps once then sets gDone 
to true. When you quit normally (by choosing Quit from the 
AEHandlcr’s File menu), you won’t hear this beep. 

Tin. Next Month 

Become comfortable with the AEHandler code so you can 
have all your own Mac applications support at least the four 
required Apple events. Play around with the AEHandler code. 
Add error-handling code where appropriate (for instance, the 
Open Document handler can call AEDisposeDesc() in response to 
errors returned by calls to AEGetParamDesc(), AECountltems(), and 
AEGetNthPtr()). Add some code to the Open Document handler to 
open the specified file and display info about the file in its 
window (maybe the file’s size). While you wait for the next 
column, read up on the Apple Event Manager in Inside Macintosh: 
Interapplication Communication. See you next month... 


I 
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Put a Face on AppleScript! 


Love AppleScript but need an interface? 


FaceSpan, the interface builder for AppleScript, 
dramatically increases the power and usability of your 
scripts. 

Whether you want to create a custom tool palette 
that gives you quick access to your favorite scripts, a 
floating window that ties together the functionality of 
multiple applications or a full-featured AppleScript 
application... 

FaceSpan is the answer. 

"If AppleScript is a hidden jewel in the Mac OS, 
then FaceSpan is its most brilliant exposition." - Howard 
Oakley, 4 1/ 2 Mice, MacUser UK 

"No scripter's workshop should be without 
FaceSpan." - Tim Warner, 4 Stars, Macworld 



Example of an interface created in FaceSpan. 


To order FaceSpan or for additional information: 

1-800-322-3772 (USA) 

1-801-226-2984 (Other Countries) 
1-801-226-8438 (Fax) 
sales@facespan.com (E-mail) 

http://www.facespan.com 



Automate 

often-repeated 

tasks. 


Rapidly build 
applications & 
prototypes. 


Customize 

existing 

applications. 


Integrate 

multiple 

applications. 


Personalize 
your computing 
environment. 


Features new to FaceSpan 3.0 allow you to: 


• Create interfaces that conform to the 
Mac OS 8 look and feel. 

• Utilize new supported display objects 
such as tab panels, disclosure triangles 
and bevel buttons whose functionality is 
built in. 

• Define linkages that hide/show or 
enable/disable window items when 
another item is hilited. 

• Develop hierarchical menus and assign 
command key modifiers directly. 
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New! Expanded 
tool palette! 


• Select applications over which floating windows 
appear. 


• Launch FaceSpan applications up to 5X faster. 


FaceSpan 

A Product of Digital Technology International 


© 1998 Digital Technology International. All rights reserved. Fac eSpan is a trademark of Digital Technology International. AppleScript is a trademark of Apple Computer, Inc., registered in the United Slates and other countries. 
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Edited by Bob Boonstra 


Porting Mac Graphics to the BeOS 


Translating your Mac 
application’s drawing 
routines to BeOS code 

Overview of Graphics and the BeOS 

For the most pan, the scope of this 
article is limited to explaining how to 
convert your Mac application’s graphics- 
related Toolbox calls to code that 
integrates into a Be application. To get a 
more general overview of Mac OS to 
BeOS porting issues, refer to the MacTech 
Magazine article “Porting Code to the 
BeOS' by Michael Rutman, Vol. 13, No. 1 
(January 1997). If you don’t know the 
fundamentals of BeOS programming, 
you’ll need to learn how to make use of 
what Be refers to as the software kits. How 
to work with the software kits is a topic 
well beyond the scope of a magazine 
article — you’ll want to refer to one or 
more of the BeOS programming resources 
listed at the end of this article. With that 
said, I still feel compelled to devote just a 
few paragraphs to summarizing how to 
use the kits to program the BeOS! After 
that I move to the real matter at hand — 
how to go about translating some 
commonly implemented Mac OS graphics 
code to BeOS graphics code. 


Structure of the BeOS 

Be applications run on BeOS-compatible computers, which 
now include PowerPC-based Macs and most Intel Pentium-based 
PCs. Between the hardware and a Be application lies the BeOS 
operating system software that consists of three layers: a 
microkernel layer that communicates with the computer’s 
hardware, a server layer consisting of a number of servers that 
each handle the low-level work of common tasks (such as 
printing), and a software kit layer that holds several software kits 
— dynamically linked libraries (DLLs) that act as a programmer’s 
interface to the servers and microkernel. 

Kits and classes 

Collectively, the software kits make up the BeOS application 
programming interface (API). Each kit consists of a number of 
object-oriented classes that a programmer makes use of when 
writing a BeOS program. Together, all the classes in die kits forni 
an application framework. While the code that constitutes your Be 
application will most likely include objects derived from classes 
defined in many of the kits, it will always include objects derived 
from classes in two kits: the Application Kit and the Interface Kit. 

A Be application defines an object of a class you derive from 
the BApplication class. This application object represents the 
application itself. Hie BApplication class, obviously enough, is 
defined in the Application Kit. Other classes in this kit establish 
a messaging system that makes applications aware of events 
(such as a click of a mouse button by the user). This kit also give 
applications the power to communicate with one another. 

The Interface Kit is by far the largest of the software kits. 
The classes of this kit exist to supply applications with a 
graphical user interface that fully supports user-interaction. The 
definition of windows and the elements that are contained in 
windows (such as scroll bars, buttons, lists, and text) are all 
handled by classes in this kit. Any program that opens a window 


Dan Parks Sydow is the author of over a dozen programming hooks, “Programming the Be Operating System " by O’Reilly & 
Associates. Dan recendy had the pleasure of visiting die Menlo Park, CA headquarters of Be, Inc. to talk with Ik* Chairman and 
CEO Jean-Louis Gassee and a number of Be engineers. He left thoroughly convinced that the BeOS is destined to be an 
important digital media tool for tab programmers and end-users. 
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uses the Interface Kit. Most of the classes mentioned in this 
article (such as the BRect class for creating rectangles, the 
BRegion class for creating regions, and the BWindow class for 
creating windows) are a part of the Interface Kit. In the area of 
graphics, one of the most important Interface Kit classes is the 
BView class. Instances of this class — and of the many classes 
derived from it — are all types of views. 

Views 

In Macintosh programming, drawing takes place within a 
port in a window. Somewhat analogous to that on the Be side is 
the view. In a Be program, drawing doesn’t take place directly 
within a window (a BWindow object). Instead, it takes place 
within a view (a BView object, or an object derived from the 
BView class). Unlike a Mac port, however, Be views can be 
nested. Views aren’t readily discernible to the end-user — they 
exist as a programmer’s means of establishing different drawing 
areas. Typically a window will hold an all-encompassing view, 
and then one or more views within that main view. Each view is 
a self-contained drawing environment, so each view can display 
text and graphics that appear different from that displayed in 
other views within the same window. That is, each view can 
display text in its own font, draw lines in a thickness different 
from lines drawn in other views, and so forth. This technique of 
allowing each BeOS view to keep irack of its own drawing 


environment deviates from the Mac OS, where drawing 
parameters are stored in QuickDraw globals. 

Because all drawing must take place in a view, everything 
you see within a window appears in a view. A scroll bar, button, 
picture, or section of text each lies within its own view. The Be 
window titled “Ilello” in Figure 1, for example, holds several 
views. Each radio button resides in its own view, as does Lhe one 
pushbutton. The framed text also exists in its own view. There 
may also be one large view that holds all these individual views 
(you’re looking at the window as an end-user, so you can’t 
determine if that’s true or not!). 


■ 

Hello 


One Beep 
! Two Beeps 


Beep 


nUe 

(Beeping 

‘WiiuCowl 


Figure 1. A Be window holds a number of views. 
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A view is capable of responding to a message that’s sent 
from the system to a BWindow object and then on to the view. 
This messaging system is the principle on which menus and 
controls work. It is also a topic worthy of much examination, 
and is beyond the scope of this article. There is one messaging 
topic worthy of note here, however — window graphics 
updating, or refreshing. 

In the Mac world, a program becomes aware of the need to 
update a window when the program’s event loop call to 
WaitNextEvent() obtains an event of type updateEvt from the 
system event queue. On the Be side, when a view needs 
updating a message is automatically issued by the system. This 
message is sent to the affected window, and from there it is 
directed to the proper view. If more than one of a window’s 
views needs updating, more than one message will be sent to the 
window (one per affected view). The BView class (from which all 
views are derived) includes a Draw() member function that 
automatically gets invoked when a view object receives such a 
message. Iliis Draw() function performs the drawing appropriate 
for that one view. 

Drawing the contents of a BView is often application- 
specific. In such an instance it’s up to your application to 
override the Draw() function of that view, and to supply the view¬ 
drawing code within the new version of the Draw() function. 
Consider the window shown in Figure 1. If the entire window is 
obscured, then brought back into view, a number of Draw() 
functions will be automatically invoked. A radio button is an 
object of the BRadioButton class, which is derived from the 
BControl class, which itself is derived from the BView class — so 
each radio button has a Draw() function. Similarly, the pushbutton 
is a view — the BButton class is also derived from the BControl 
class. Each of these three controls have a Draw() function that 
gets invoked. Fortunately for you, the programmer, these Draw() 
functions know how to draw the appropriate control without any 
help from your code. The framed text is of more interest to you. 
The rectangle and text reside in an object of an application- 
defined class derived from the generic BView class. Here the 
BView version of Draw() needs to be overridden and implemented 
such that it draws the desired contents. Most of the graphics¬ 
drawing code covered in this article will become a part of the 
Draw() function (or of an application-defined function invoked by 
Draw()) for one of your program’s views. 

Color 

Hopefully your Macintosh application holds the user’s 
attention by making heavy use of color. If it does, and you’re 
interested in porting it to the BeOS, you’re in luck — just about 
any use of color in your Mac program can be easily duplicated 
in its Be counterpart. 

RGB colors 

In the Mac OS, QuickDraw allows you to define colors using 
the RGB color space. In short, a color space is a scheme, or 
system, for representing colors as numbers. A QuickDraw color 
is made up of the combination of three color components: red, 


green, and blue. The T<x>llx)x RGBColor data type consists of 
three 2-byte unsigned short fields — one for each color 
component. Each of the three color components is defined by a 
value with a range of 0 to 65,535. A component value of 0 means 
none of that component is present in the overall color, while a 
value of 65,535 means that the component is intensely present in 
the overall color. The BeOS is capable of defining colors using 
any of several color spaces, including the default system that 
defines colors using the RGB system. In Be’s version of the RGB 
system, 32 bits are used to define the color of a single pixel. The 
Be data type rgb_color is a struct with four fields. Each field (red, 
green, blue, and alpha) is of type uint8 (an unsigned 8-bit integer), 
so each component can have a value in the range of 0 (no 
presence of that component in the color) to 255 (full presence). 
The remaining eight bits (the alpha field) are reserved for a future 
implementation of a byte that will be used to specify a 
transparency level for the overall color. When implemented, an 
alpha value of 0 will result in a color that is completely 
transparent, while an alpha value of 255 will result in a color that 
is completely opaque. 

Converting a Mac color to a BeOS color is as easy as 
redefining your RGBColor variable as an rgb_color variable, 
scaling the value of each of the three color components 
accordingly (from a range of 0 to 65,535 on the Mac OS to a 
range of 0 to 255 on the BeOS). To establish a BeOS color you 
can assign values to the four fields of an rgb_color variable at the 
time of declaration. In the following snippet note that the unused 
alpha field is set to 255 in preparation for the time when Be 
supports transparency: 

rgb_colorblueColor = (0, 0, 255, 255); //(r.g.b.a) 

You can also choose to assign each component individually 
at any time after the variable is declared: 

rgb_col orredColor; 

redColor.red = 255: 
redColor.green = 0; 
redColor.blue = 0; 
redColor.alpha = 255; 

Using a color 

On the Mac, you typically make use of an RGBColor variable 
by passing it to the Toolbox function RGBForeColor() to set the 
foreground color — the color used in all subsequent drawing 
routines. On the BeOS, an rgb_color variable is most often used in 
the setting of two colors that a view keeps track of: the view’s high 
color and low color. While these names seem to imply that the two 
colors must be quite different from one another, that needn’t be 
the case. 'ITie high and low colors are simply two colors that can 
be used individually or mixed together in drawing operations. 
When drawing takes place in the view, you specify whether the 
current high color, the current low color, or a mix of the two colors 
should be used. The BView member functions SetHighColor() and 
SetLowColorQ alter the current high and low colors of a view. Pass 
SetHighColor() an rgb_color and that color becomes the new high 
color — and remains as such until the next call to SetHighColor(). 


18 


Porting Mac Graphics to the BeOS 


MacTech • Seitember 1998 







The Setl_owColor() routine works the same way. This next snippet 
uses the just-defined redColor and blueColor variables to set a 
view’s high color to red and its low color to blue: 

SetHighColor(redColor); 

SetLowColor(blueColor); 


A call to one of the color-setting functions doesn’t actually draw 
any tiling — it only sets two color characteristics of a view. Exactly 
how the high and low colors affect subsequent shape drawing is a 
topic best covered after the upcoming discussion on patterns. 


Allowing the user to choose a color 

Assigning numerical values to the red, green, and blue 
components of a color is something a programmer might not 
have a problem with — but the end-user shouldn’t be forced to 
select a desired color using this somewhat unfriendly technique. 
On the Mac, users choose an RGB color by means of the Color 
Picker. The RGB Picker in the Appearance control panel provides 
an example of a typical use of the Color Picker. Your own 
Macintosh program can bring up the Color Picker at any time by 
calling the Toolbox function GetColor(). Analogous to the Color 
Picker on the Be is the color control. Your Be program creates 
an object of the BColorControl class in order to allow a user to 
select an RGB color — without the user knowing anything about 
the RGB color system or RGB values. What the BColorControl 
object displays to the user depends on the number of colors the 
user’s monitor is currently displaying. The user can set that 
parameter by choosing Screen from the preferences menu in the 
Tracker. The Screen preferences window itself includes a 
BColorControl object, so that preferences window is worth 
examining. Figure 2 shows the Screen window for a monitor set 

i-r-\ r\ /"*T r/-\f/^ Q hifo UT/x^-i fU r~\ i n fU /X 
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matrix, or block of squares, at the bottom of the Screen window. 
In Figure 3, with the monitor adjusted to use 32 bits for each 
pixel, the color control appears as the four horizontal bands at 
the bottom of the Screen window. 



Figure 2. The Be Screen preferences , which includes a color 
control, at 8 bits per pixel 



Screen 


Figure 3> The Be Screen preferences, which includes a 
color control, at 32 bits per pixel 


To include a color control in your own program, declare a 
BColorControl object and the variables that will be used as 
arguments to the BColorControl constructor. Then use new to 
create the new object: 

BColorControl *theColorControl; 

BPoint leftTop(20.0, 50.0); 

color_conirol_layout matrix = B_CELLS_32x8; 
long cellSide = 10; 

theColorControl = new BColorControl( leftTop, matrix. 

cellSide. “MyColorCntl"); 
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left-top corner of the color control. The matrix argument is of the 
Be-defined data type color_contro!_layout. When the user has the 
monitor set to use 8 bits per pixel, the 236 system colors are 
displayed in a matrix. This parameter specifies how these squares 
should be arranged. Use one of five Be-defined constants here: 
B_CELLS_4x64, B_CELLS_8x32, B_CELLS_16x16, B_CELLS_32x8, 
B_CELLS_64x4. The two numbers in the name of each constant 
represent the number of columns and rows, respectively, that the 
colored squares are to lie placed in. For instance, the 
B_CELLS_32x8 constant will display the 256 colors in eight rows, 
with 32 colored squares in each row. The cellSide argument 
determines the pixel size of each colored square in the matrix. A 
value of 10, for instance, results in 256 squares that are each 10- 
pixels-by-10-pixels in size. The final argument provides a name 
for the color control object. The BColorControl class is derived 
from the BControl class, which in turn is derived from the BView 
class. Every view' has a name that can be used elsewhere in your 
code to access the view. The name can be supplied using a string 
(as shown in the above snippet) or by passing in a constant 
variable that was defined as a character constant: 


const char *name = “MyColorCntrl”; 
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I’ve discussed the BColorControl constructor arguments as if 
they will be used when the user has the monitor set to use 8 bits 
for the display of color in each pixel. For the argument values 
used in the previous snippet, the resulting color control looks 
like the one displayed in the Screen window in Figure 2. If the 
user instead has the monitor set to 32 bits for each pixel, the 
same arguments are used in the display of four bands, three of 
which the user clicks on in order to create a single color (the top, 
gray band represents the currently unimplemented alpha, or 
color transparency level component). Here, instead of being 
used in the determination of the arrangement and size of a matrix 
of color squares, the arguments are now used to determine the 
shape and overall size the four bands occupy. 

When a window displays a color control, the user selects a 
color by clicking on its cell (if the user’s monitor is set to 8 bits 
per pixel) or by clicking on a color intensity in each of the three 
color component bands (if the user’s monitor is set to 32 bits per 
pixel). In either case, the BColorControl object always keeps track 
of the currently selected color. Your program can obtain this 
color at any time via a call to the BColorControl member function 
ValueAsColor(). Here a program obtains the user’s current color 
choice and saves it in the variable userColorChoice: 

rgb_coloruserColorChoice; 

userColorChoice = theColorConlrol >ValueAsCo1or(); 

While devoting 32 bits per pixel to a color is a popular 
technique for defining a program’s colors, note that Release 3 of 
the BeOS includes a 16 bits per pixel option that functions 
similarly to the 32 bit per pixel option discussed above. 

Patterns 

Both on the Mac OS and the BeOS, a pattern is an 8-pixel- 
by-8-pixel area that can be “poured" into any specified area in 
order to give that entire area a uniform look. 

Be-defined patterns 

The Mac OS provides five predefined patterns that are a part 
of the QDGIobals data structure qd: dkGray, ItGray, gray, black, and 
white. The BeOS has no analogous data structure, but ii does 
supply you with three patterns that are always available for your 
program’s use. Each of these patterns is represented by a Be- 
defined constant: B_SOLID_HIGH is a solid fill of the current high 
color, B_SOLIDJ_OW is a solid fill of the current low color, and 
B_MIXED_COLORS is a checkerboard pattern of alternating 
current high color and current low color pixels. Earlier you saw 
how to define a color and then use it to set the high or low color 
of a view. Now that you know about patterns, you’re ready for 
an example of using an RGB color. This next bit of code draws 
a solid red rectangle: 

BRect theRect(20.0, 10.0, 220.0. 110.0); //l,t,r,h 

rgb_colorredColor = 1255. 0, 0, 255); 

SetHighColor(redColor); 

FillRect(theRect); 


The above snippet introduces the BRect class. 1 cover this 
class in more depth ahead, but I’ve brought it into play now 
because I need to draw something here! The BRect class is used 
to create a BRect object, which serves to define a rectangle. 
Unlike most classes in the BeOS API, the BRect is thought of 
more as a primitive data type than as a class: it’s not derived from 
any other class, all its data members are public, and it includes 
no virtual member functions. Typically, you create a rectangle 
object by simply declaring a BRect variable — you don’t use new 
to allocate memory for the object. As shown above, assigning 
pixel coordinates to the rectangle can be done by listing them in 
the order left, top, right, bottom at the rectangle object’s 
declaration. Like the Mac OS, the BeOS uses a coordinate system 
based on coordinate pairs: the top-left pixel is considered pixel 
(0.0, 0.0). Pixel numbering increases as you move to the right, 
and as you move down. Unlike in the Mac OS, pixels are floating 
point values in the BeOS. Integral BeOS coordinate values fall in 
the center of a screen pixel, unlike the Mac OS, where the 
coordinate value represents the upper left corner of a screen 
pixel. Again like the Mac OS, on the BeOS the screen itself is a 
global coordinate system, and each window has its own local 
coordinate system. Additionally, every view in a BeOS window 
has its own coordinate system. 

In general, to draw in a view you call a BView drawing 
function. In particular, to draw a rectangle in a view you call the 
BView function FillRect(). Consider yourself forgiven if your first 
thought was that FillRectQ must be a member function of the 
BRect class rather than the BView class! By default, FillRect() fills 
the specified rectangle with the high color. The above snippet 
sets the high color to red — so that’s the color the rectangle 
theRect will be. You can also tell FillRect() to use a particular 
pattern (whether one of the three Be-defined patterns or an 
application-defined pattern) by including an optional second 
argument. This next snippet defines a blue color and uses it in 
the setting of the low color. The line that follows draws the 
rectangle theRect in blue: 

rgb_colorblueColor = 10. 0. 255. 2551; 

SetLowColor(blueColor); 

FillRect(theRect. B_S0LID_L0W): 

Creating a pattern 

For monochrome patterns on the Mac, you can use the 
above-mentioned qd patterns, the 38 patterns that make up the 
System pattern list, or define your own ‘PAT ‘ pattern resources 
in a resource editor. For color patterns you c an define your own 
‘ppat’ pixel pattern resources. On the BeOS you define patterns 
within your source code. Using a variable of the data type pattern 
you specify whether each of the 64 pixels of a pattern should be 
filled with the current high color or current low color. Here’s the 
pattern data type: 

typedef struct ( 
uchar data [8]; 

) pattern; 
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To create a pattern you declare a pattern variable and 
initialize each of its eight fields with a hexadecimal pair. Each of 
the eight elements in the pattern array is one byte in size, so each 
can hold a single unsigned value in the range of 0 to 255. Each 
of the hexadecimal pairs in each of the eight rows in a pattern 
falls into this range (0x00 = 0, Oxff = 255). To create a pattern 
variable, determine the hexadecimal pairs for the pattern and 
assign the variable those values. In Figure 4 you see that I drew 
an 8-by-8 grid and filled in the squares that I want to be 
represented by the high color, and left blank the squares I want 
to be represented by the low color. The left side of the figure 
shows the binary representation of each row in the pattern, with 
a row looked at four bits at a time. The right side of the figure 
shows the corresponding hexadecimal value for each row. 
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cc 
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Figure 4. 1 he binary and hexadecimal representations 
of a pattern. 


lb convert a Macintosh pattern, view it in your Mac resource 
editor and determine which pixels you want “on” and which you 
want “off.” Then write down the numerical representation of the 
pattern, as 1 did in Figure 4. At this time you won’t be concerned 
with pattern color — just consider that an “on” pixel will be one 
color, and an “off’ pixel will be a different color. 

In Figure 4, the binary representation of each pixel row is 
for the benefit of showing how I came up with the hexadecimal 
row value. When initializing the pattern variable, use the 
hexadecimal values — like this: 

pattern stripePattern = ( Oxcc, 0x66, 0x33, 0x99, 

Oxcc, 0x66, 0x33, 0x99); 


Using a pattern 

On the Mac, you make use of a pattern in a variety of ways. If 
the pattern is one of the five qd-defined patterns, you simply use 
a pointer to it in a drawing routine — as in passing &qd.black to 
FillRect(). If the pattern is included in a pattern list (a resource of 
type TAT#’), then you use a call to the Toolbox function 
GetlndPattern() to load the desired pattern to use. If the pattern is 
an individual resource of type TAT then you load it by calling 
the Toolbox function GetPattern(). You’ve seen that on the BeOS 
there is no qd global data structure, and that patterns don’t exist 
as resources. So in all cases you should draw out the Mac pattern 
and define it as a BeOS pattern variable, as shown above. 

On its own, a Be pattern variable holds no color information. 
When it comes time to use a pattern variable, the colors used in 
the pattern are dependent on the current high and low colors. In 
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this next snippet a striped pattern is defined, anci the high color 
is set to red and the low color to blue. When the rectangle 
theRect is filled with the striped pattern, it will end up with red 
and blue diagonal stripes: 

BRect theRect(20.0, 10.0, 220.0, 110.0); 

rgb colorredColor = (255, 0. 0. 255); 

rgb colorblueColor - 10, 0, 255, 255); 

pattern stripePattern = I Oxcc, 0x66, 0x33, 0x99, 

Oxcc, 0x66, 0x33, 0x99); 

SetllighColor(redColor) ; 

SetLowColor(blueColor); 

FillRect(theRect, stripePattern); 

Drawing Pen 

Like the Mac OS, the BeOS uses the concept of an imaginary 
graphics pen when carrying out drawing operations. On both 
operating systems, the pen exists as a way to summarize and 
express properties of a drawing environment. 

Pen Location 

Mac programmers call the Toolbox functions Move() and 
MoveTo() to establish the starting location for the next drawing 
operation. On the BeOS convert calls to these routines to calls to 
the BView functions MovePenByO and MovePenTo(). Pass the Be 
function MovePenTo() a pair of float values representing the 
coordinates of the pixel to move to: 

MovePenTo(20.0, 70.0); 

Like MovePenTo(), the MovePenByO function moves the 
starting location for drawing. MovePenTo() moves the pen relative 
to the view’s origin. MovePenByO moves the pen relative to its 
current location in the view. Consider this snippet: 

MovePenTo(20.0. 70.0): 

MovcPcnBy(40.0, 10.0); 

The call to MovePenTo() moves the pen to the location 20 
pixels right of the view origin and 70 pixels down from the 
top of the view. That places the pen at the point (20.0, 70.0). 
The call to MovePenByO uses this current location as the 
reference and moves the pen 40 pixels to the left and 10 
pixels down. The result is that, relative to the view’s origin, 
the pen is at the point (60.0, 80.0). 

As with the Mac Toolbox function Move(), negative values 
for the BeOS function MovePenByO move the pen “backwards” in 
the view. A negative horizontal argument moves the pen to the 
left, while a negative vertical argument moves the pen up. 

Pen Size 

On the Mac OS, the pen’s size — the thickness at which 
lines are drawn — is by default one pixel in width and one pixel 
in height. This pen size can be altered with a call to the Toolbox 
function PenSize(). On the BeOS, the pen has a single thickness 
which results in lines having the same width and height. You call 
the BView function SetPenSize() to alter this pen diameter: 

SetPenSize(3.0); 


When altering the pen size, the best technique is to obtain 
and save the current pen size, change it, perform the desired 
drawing using the new pen size, then restore the pen to the 
saved size. The BView member function PenSize() allows you to 
do that. When invoked, PenSize() returns a float that holds the 
current thickness of the pen: 

float savedPenSize; 
savedPenSize = PenSizeO: 

Shapes 

I’ve already demonstrated how to use the graphics pen, 
what the coordinate system is, and how to set up and draw a 
rectangle. As you may have guessed, you’re well on your way to 
drawing just about any shape in your Be program. 

Points 

On the Mac, a point is represented by a variable of the type 
Point. The Point is a data structure consisting of two short values: 
h is the horizontal coordinate of the point, while v is the vertical 
coordinate. On the BeOS, a point is represented by a BPoint object. 
The BPoint object consists of two floating point values: x denotes 
the horizontal coordinate, while y denotes the vertical coordinate. 

A BPoint object can have values assigned to its coordinate pair 
members either at the time of declaration or anytime thereafter. At 
declaration, one of the BPoint constructors can be used to take care 
of the task of assigning values to the BPoint members: 

BPoint thePoint(40.0, 70.0); 

If the assignments are to lx: made after the object’s 
declaration, then this can be done either by using the BPoint 
member function Set() or by assigning values directly to the x 
and y data members: 

BPoint thePoint; 

BPoint anotherPoint; 

thePoint.Set(100.0, 200.0); 
anotherPoint.x = 100.0; 
anotherPoint.y = 200.0; 

Like the BRect class, the BPoint class acts much like a data 
type. You create a point object by simply declaring a BPoint 
variable (as opposed to allocating memory using new), and you 
can alter its data members either by direct assignment or by 
invoking the Set() member function. 

Lines 

'lo draw a line on the Mac you position the graphics pen 
using calls to Move() or MoveTo(), then invoke the Toolbox 
function Line() or LineTo(). To draw the same line under the 
BeOS, call MovePenByO or MovePenTo(), then invoke the BView 
function StrokeLine(). 

BPoint start(50.0, 50.0); 

BPoint end(150.0, 50.0); 

MovePenTo(start); 

StrokeLine(end); 
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Optionally, you can also omit the pen-placement and simply 
pass StrokeLine() two parameters: each a BPoint object thaL 
represents the starting and ending point of the line, respectively: 

Stroke!,ine(start, end); 

Both versions of StrokeLine() offer a final optional parameter 
that can be used to specify a pattern in which the line is drawn. 
Here the diagonal stripe pattern discussed earlier in this article is 
used. The high color is set to red, and the low color is left in its 
default state of white. Additionally, the pen size is set to 10.0. 
The result is a line 10 pixels in thickness with diagonal red stripes 
running through it: 

rgb_colorredColor ~ 1255, 0. 0, 255); 

BPoint start(50.0, 50.0); 

BPoint end(150.0, 50.0); 

SetHighColor(redColor); 

SetPenSize(10.0); 

StrokeLine(start, end, stripePattern); 

Rectangles 

I’ve already described how to set up and fill a rectangle — 
so 1 can be brief here as I formalize the explanations. The BRect 
class has four floating-point data members (left, top, right, and 
bottom) that are used to specify the coordinates of a rectangle. 
You can assign these data members values in a variety of ways. 
At. the rectangle variable’s declaration you can assign the 
members values individually: 

BRect theRect(10.0, 30.0, 110.0, 130.0); 

Alternatively, you can set up the rectangle by specifying the 
left-top coordinate and right-bottom coordinate: 

BPoint leftTopPt(10.0. 30.0); 

BPoint rightBottomPt(110.0, 130.0); 

BRect anotherRect(leftTopPt, rightBottomPt); 

On a Mac you set up a rectangle either by making direct 
assignments to a Rect variable’s left, top, right, and bottom fields, 
or by calling the Toolbox function SetRectQ. On the BeOS a 
BRect object’s data memlxrrs are similarly given values: use direct 
assignments or call the BRect function Set(). 

BRect theRect; 

BRect anotherRect; 

theRect.left = 10.0: 
theRect.top = 30.0; 
theRect.right - 110.0; 
theRect.bottom = 130.0; 

anotherRect.Set(10.0. 30.0, 110.0, 130.0); 

The BRect class also contains member functions LeftTop(), 
LeftBottomQ, RightTop(), and RightBottom() that provide access to 
any of the points in the rectangle. Similarly, there are functions 
like SetLeftTop() to modify those point values. 

After setting up a rectangle in your Macintosh program, you 
frame it by calling FrameRect(), fill it with the current pattern (as 
established by a call to the Toolbox function PenPat() or 
PenPixPatQ) by calling PaintRectQ, or fill it with a specified 


pattern by calling FillRect(). In a Be program, frame the rectangle 
by calling StrokeRect(), and fill it by calling FillRect(). Both 
StrokeRect() and FillRect() allow for an optional second argument 
that specifies the pattern to use in drawing the rectangle. If 
omitted, a solid pattern using the current high color 
(B_SOLID_HIGH) is used by default. 

BRect theRectdO.O, 10.0, 160.0, 160.0); 

BRect anotherRect(30.0, 30.0. 140.0, 140.0); 

StrokeReci(theRect, B MIXED COLORS); 

FillRect(anotherRect, stripePattern); 

Round rectangles 

Both the Mac OS and the BeOS rely on the rectangle (rather 
than a unique round rectangle data type or class) as the basis for 
a rectangle with rounded corners. On the Mac you’ve used die 
Macintosh Toolbox functions FrameRoundRect(), PaintRoundRect() 
and FillRoundRect(). On the BeOS you use the BView functions 
StrokeRoundRect() and FillRoundRect(). For your Be round 
rectangle, first declare a BRect variable and set up the rectangle. 
Then pass that rectangle and ihc amount of rounding that is to 
be applied to each corner as arguments to StrokeRoundRect() or 
FillRoundRect(). The degree of rounding is determined just as it is 
for a Mac round rectangle: the second and diird arguments 
together specify the shape of an ellipse (the second parameter 
establishes the ellipse radius along the x-axis, while the third 
parameter establishes the ellipse radius along the y-axis). Such an 
ellipse can be thought of as being set in each corner of the 
rectangle. Then, only one quarter of the ellipse is actually drawn 
in order to form a rounded corner. The following snippet 
demonstrates how to create a round rectangle that’s filled with 
the current low color: 

BRect theRect(30.0, 30.0, 130.0, 130.0); 

FillRoundRect(theRect, 20.0, 20.0); 

Ellipses 

After defining a rectangle, an ellipse is drawn by inscribing 
an oval within the lx>undaries of the rectangle. The rectangle 
itself isn’t drawn — it simply serves to specify the size of the 
ellipse. This is similar to how an ellipse is drawn in a Mac 
program. In the Mac OS you pass a pointer to a rectangle to 
FrameOval(), PaintOval(), or FillOval(). In the BeOS, you use the 
BView member functions StrokeEllipse() and FillEllipse(): 

BRect theRect(30.0, 30.0, 130.0, 130.0); 

FillEllipse(theRect, B S0LID_L0W); 

StrokeEllipse(theRect. B SOLID HIGH); 

Polygons 

A polygon is a closed shape that has three or more sides. Your 
Macintosh program creates a polygon by declaring a PolyHandle 
variable and then calling OpenPolyO and ClosePoly(). Between the 
open and close calls should be a MoveTo() call that positions the 
graphics pen, and a series of calls to LineTo() that then draw the 
lines that make up the edges of the polygon. Rather than a series 
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of edge-defining lines, the BeOS treats a polygon as a series of 
vertex-defining points. To create a Be polygon, first declare an 
array of BPoints. The number of points should be the number of 
polygon vertices. Use the BPoint function Set() to define each 
vertex. Then declare and create a new BPolygon object. The 
BPolygon constructor accepts as its arguments the array of BPoints 
along with an int32 (32-bit integer) value that specifies how many 
points are in the array. Here’s how a BPolygon object representing 
a three sided polygon might be defined: 

BPoint pointArray [3] ; 

int32 numPoints = 3; 

BPolygon ‘thePolygon; 

pointArrayfO].Set(50.0, 100.0); 
pointArray[1].Set(150.0. 20.0); 
pointArray[2].Set(250.0. 100.0); 

thePolygon = new BPolygon(pointArray, numPoints); 

On the Mac, after a call to ClosePoly() is made, the lines that 
make up the polygon are treated as a single entity. The polygon can 
be drawn using the Toolbox functions FramePoly(), PaintPoly(), and 
FillPoly(). In your Be program, once a BPolygon object is defined, its 
outline can be drawn by calling the BView member function 
StrokePolygon(), or it can lie filled in by calling FillPolygon(). As with 
other drawing routines, omitting the pattern argument tells the 
function to use B_SOLID_HIGH as the fill pattern. If you want to use 
a different pattern, specify it as a second argument. Here I’m filling 
the just-clefined polygon with my earlier-created striped pattern: 

FillPolygon(thePolygon, stripePattern); 

Regions 

A Macintosh region is fanned much as a Macintosh polygon is: 
a series of calls to Toolbox drawing functions define the area that’s 
to be considered one region. A new’ RgnHandle is created using a call 
to NewRgn(). and OpenRgn() and CloseRgn() calls frame the region- 
defining Toolbox calls. A BeOS region is instead created by defining 
any number of rectangles that are then grouped together into a single 
BRegion object. The rectangles that make up a region can vary in 
size, and can be defined such that they fonn one continuous shape 
or any numt>er of seemingly unrelated shapes (that is, die one region 
can be composed of non-touching rectangles). To set up a region, 
first create a new BRegion object Then define a rectangle and add 
diat rectangle to the BRegion object. The steps of defining and adding 
rectangles to the BRegion object can be repeated until the area that 
is to lie considered a single region is complete. Tn the following 
snippet two rectangles are defined and added to a BRegion object: 

BRect theRect; 

BRegion * theRegion; 

theRegion = new BRegionO; 
theRect.Set(20.0, 20.0. 70.0. 70.0); 
theRegion >Include(theRect); 

theRect.Set(50.0. 50.0, 150.0. 100.0); 
theRegion*>Include(theRect); 


On a Mac you frame and fill a region using calls to 
FrameRgn() and FillRgn(). Because a Be region can consist of any 
number of overlapping rectangles, outlining each individual 
rectangle would result in lines running through the content area 
of the region — so no StrokeRegion() function exists. Instead, 
display the region by invoking the BView member function 
FillRegion(). Here the region that was created in the previous 
snippet is filled with the default B_SOLID_HIGH pattern: 

FillRegion(theRegion); 

One important use of a region is in testing for the inclusion 
of a point within an area. On the Mac you use the Toolbox 
function PtlnRgn() to see if the cursor was over the area of a 
region when the mouse button was clicked. On the BeOS, test a 
point for inclusion in a region by calling the BRegion member 
function Contains(). Pass this routine the BPoint object to test, and 
Containsf) returns a bool (Boolean) value that indicates whether 
or not the tested point lies within the region. In this next snippet 
a region consisting of just a single rectangle is defined. A point 
is then defined and tested for inclusion in this region: 

BRect theRect(20.0, 20.0. 70.0. 70.0); 

BRegion ‘theRegion; 

BPoint thePoint(60.0, 90.0); 

theRegion = new BRegionO; 
theRegion->Include(theRect); 

FillRegion(theRegion); 

i f (theRegion >Contains (thePoint)) // point in region 

// do something 

else // point not in region 

// do something else 

Last Word 

For learning new programming techniques, there’s no 
better way to get the complete picture than to view a well- 
commented source code listing for a complete program. Rather 
than use up valuable magazine pages, I’ve opted to make such 
a listing available at MacTech’s web site. After downloading, 
view the code by opening the GraphicsEx.cp file from within 
the BelDE (if you have the BeOS, you have a version of 
Metrowerks’ CodeWarrior for BeOS). To make use of the code, 
create a new BelDE project, add GraphicsEx.cp to it, and then 
choose Run from the Project menu. 

I’ve included a number of graphics-porting considerations 
in this article, but of course there are many more. How to move 
your Mac application’s picture-drawing and bitmap-handling 
code to the BeOS are a couple of topics that come to mind. For 
information on these subjects, as well as more general BeOS 
programming information, refer to the BeOS API reference 
book u Be Developer’s Guidef by O’Reilly & Associates, or to my 
own BeOS tutorial “ Programming the Be Operating System ,” 
also by O’Reilly & Associates. 

m 


24 


Porting Mac Graphics to the BeOS 


MacTech • September 1998 








^§FREE! 

Making CD-ROMs: 

An Essential Guide for Independent 
Producers and Business Users 



"Nicely organized and easy to 
understand for the novice who 
doesn't know where to start. 



This booklet guides you through 
the entire process of creating 
and marketing a new CD-ROM title. 
It's thirty-six pages of helpful 
tips on getting your project 
started, authoring techniques, 
premastering, and much more. 

We also have a full color catalog 
with dozens of creative CD-ROM 
manufacturing and packaging 
options. Our guide and catalog are 
both free — just contact us today. 


while, for the more experienced, 
it's a resource that puts a wide 
variety of important topics all 
in one place." 

— Donni Magid, President 
Independent Media Production 
Huntingdon Valley, PA 



www.discmakers.com/romguide 

1-800-CD-R0M-N0W 

( 1 - 800 - 237 - 6666 ) 


NEW JERSEY Plant & Main Office 

7905 N. Route 130, Pennsauken, NJ 08110-1402 

1-800-237-6666 • 609-663-9030 • FAX 609-661-3450 

NORTHERN CALIFORNIA Plant & Regional Sales Office 
42650 Christy Street, Fremont, CA 94538-3135 
1-800-869-0715 • 510-226-0800 • FAX 510-226-0455 

LOS ANGELES Regional Sales Office 

3445 Cahuenga Blvd. West, Los Angeles, CA 90068-1329 

1-800-731-8009 • 323-876-1411 • FAX 323-876-6724 



DISC MAKERS 

CD-ROM MANUFACTURING MADE EASY 


NEW YORK Regional Sales Office 

11 West 17th St., New York, NY 10011-5504 

1-800-446-3470 • 212-645-0312 • FAX 212-352-0573 

CARIBBEAN Regional Sales Office 
Ave. Blvd. Arturo Cadilla EB18, 

Levittown, Toa Baja, PR 00949-2701 
1-800-804-9588 • 787-795-5500 • FAX 787-795-5554 













by Doug McKenna, Mathemcesthelics, Inc 
Edited by the MacTech Editorial Staff 


Resource Templates 


Programming on the Macintosh 
involves creating and managing a variety 
of complicated data structures that 
describe everything from a basic window to 
the preferences data structure of our 
specific applications. As Macintosh 
programmers we rely on resource editors , 
like Apple’s ResEdit and Mathemcesthetics 
Resorcerer to view and manipulate many 
of those data structures. In turn, those 
resource editors rely on TMPL type 
resources to define and record the 
structure of all other types of resources. In 
this article , Doug McKenna (the author of 
the high performance resource editor 
Resorcerer) presents an introduction to 
TMPL resources. — The editor 

What is a Resource Template? 

Resorcerer contains a jx)weiful 32-bit 
data editor that parses blocks of data of a 
given resource type into the data’s 
constituent editable fields. It does this by 
following a set of instructions that declares 
the sequential format of the data. Each set of 
instructions is called a template , and each 
template is itself kept in a resource of type 
TMPL’. The binary data format of the 
template resource is quite simple, and can 
itself be described by another ‘TMPL*. Editing 
templates, however, is such a common and 
important activity that there is a dedicated 
editor within Resorcerer designed specifically 
for dealing with TMPL' resources. 


Each TMPL’ resource has the same internal structure for its 
own data, but the data itself describes different data formats. The 
first four characters of the TMPL’ resource’s name, when taken 
as a resource type, uniquely identify the resource type that the 
template decribes. Resorcerer pays attention to templates it finds 
installed in any of several folders next to the application which 
are reserved for keeping common or private templates; or in 
resource files that it has opened for editing; or within 
Resorcerer’s own application resources (Figure 1). TMPL' 
resources whose names are less than 4 ASCII characters in length 
are ignored. ‘TMPL’ resource IDs are also ignored. 


Appearance Templates 


7 'TMPL* (Resource Data Template) Resources: 



Figure 1 . Template Resources in a File. 


The data within each template is nothing more than an 
arbitrarily long list of data parsing instructions, also called fields. 
Each field consists of two parts: (1) a variable-length Pascal-style 
string, followed by (2) a four-byte parsing code. Instructions are 
packed one after the other; there are no pad or alignment bytes 
anywhere. There is also no initial cotint, so that the number of 
instructions in the template can only be determined by parsing 
the thing until the end of the template data is reached (Figure 2). 


Doug McKenna is the root hierarchxologist of Mathemxsthetics, Inc and has been a programmer for over 25 years. In addition 
to maintaining and enhancing Resorcerer® for the much of the last decade, he has worked on taxonomic database and music 
notation software. In his minimally-exlstent spare time, he enjoys gluing words together, hacks piano compositions, and researches 
geometric fractal tiling designs. Doug’s last article for MacTech was FEZ: Frame Evading ZoomRects, which explained his award¬ 
winning “pushing the envelope” hack at MacHack ’94. You can reach Doug at resorcercr@mathemaesthetics.com. 
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Figure 2. TMPL Structure. 

The string is called the instruction’s label } and, being Pascal, 
consists of an unsigned length byte, followed by that many bytes 
of character data. The label primarily serves to identify for the 
user of the Data Editor the meaning of each parsed data field. 
Occasionally, the label has certain special characteristics for the 
benefit of the Data Editor’s parser/formatter/interface (for 
instance, if the label is “Reserved”, “Filler”, or “Unused”, the 
editor doesn’t allow the user to edit the field), but in general the 
label is equivalent to a comment in a compiled language, and 
can be set to whatever you like. For instance, in the Japanese 
version of Resorcerer, the field labels are translated into Kanji, 

The four-byte parsing code is called the field’s type. It 
usually encodes both the size and manner of presentation of the 
next data field to be parsed sequentially from the data; however, 
there are a variety of special purpose codes that guide 
Resorcerer’s parser in higher-level ways, or which are used to 
enhance the interactive interface of the Data Editor. 

Resorcerlr is Upwardly Compatible with RrsEdit 
Templates 

Other types of template resources have been designed, 
notably for MacsBug Cmxwt’ resources) and Metrowerks’ 
Constructor (‘CTYP’ resources), both of which can in turn be 
described by Resorcerer templates. The descriptive capabilities of 
Rez templates, which are kept in source code text files rather than 
resources, are more powerful, but can only be used for compiling. 

The simple and elegant ‘TMPL’ structure described above 
was first implemented in Apple’s resource editor, ResEdit, over a 
dozen years ago. Although you can edit a minimal set of simple 
Macintosh resources with ResEdit templates, in the ensuing years 
Apple and its developers have created much larger and more 
complicated daLa structures, which ResEdit cannot support. This 
is due primarily to reliance on compiling resources with Rez, but 
also from using the enhanced features that Resorcerer has 
provided over the years. 

ResEdit supports 36 template field parsing codes; Resorcerer 
supports 128 (or more, if you count a handful of synonym field 
types implemented for mnemonic consistency). Fortunately, 
though, 34 of those 128 operate exactly the same as far as 
properly parsing data built with ResEdit, and the remaining 2 


types (Booleans and fixed-length Pascal string buffers) are 
configurable to behave compatibly or not. Thus if you’ve 
invested time in creating your own ResEdit templates and built 
resources with them, Resorcerer’s Data Editor can use your 
templates unchanged, and you can still edit the resources you or 
others have previously created. 

Differences Among Data Descriptions 

To see the differences among various ways of describing a 
well known resource, consider the different ways that the dialog 
window ODLOG ) resource can be described using Rez, ResEdit, 
Resorcerer, and C. The data format is simple enough: a few 
consecutive numeric fields, followed by a Pascal string for the 
window title, followed by another numeric field. 

Listing 1: Four ways to describe a ‘DLOG’ 

Rez Template 

type ‘DLOG’ { 
rect; 

integer documentProc. dBoxProc, plainDBox, 
altDBoxProc, 

noGrowDocProc, movablcDBoxProc, zoomDocProc = 8. 
zoomNoGrov • 12, rDocProc = 16; 
byte invisible, visible; 

fill byte; 

byte noGoAway, goAway; 

fill byte; 

unsigned hex longint; 
integer; 


GOT BUGS? 

...and you're drowning in paper 
trying to keep track of them? 

You need BugLink! 

• BugLink is a client/server application allowing you 
to connect developers, testers, and support engineers 
anywhere in the world. 

• Intuitive user interface gives you the information you 
need at a glance. 

• Fully customizable database— add the fields you need 
to each project. 

• Custom TCP/IP protocol minimizes network 
traffic— ideal for dial-up connections. 

• Client applications can operate 'off-line'— allowing 
bug entry and modification even when not connected to 
the network! 

• Cross platform— set up mixed Macintosh and Windows 
environments in minutes with no additional software 
needed! 

• Try before you buy. Download and try risk free for 
30 days from http://www.pandawave.com/bl/ 

A 5 User License starts at $299; that's only $60 per person. 

The Pand aWave 

http://www.pandawave.com 


September 1998 • MacTkch 


























BBEdit 4.5 
Serious Text Editing 
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Battle vicious aliens across a futuristic L.A 
battle ground — tell 'em Duke sent you. 


Only $29.95! (SDUKE) 


General Edit 1.02 
Serious Data Editing 


The tool of choice for editing files with 
arbitrary or complex data formats. View, 
explore, and edit files with any data 
format or unknown formats! 
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Resorcerer 2.2 
Serious Resource Editing 


CodeWarrior Pro 3 
Serious Compiling 


The industry standard in Macintosh V s 

development environments, with compilers 
for Pascal, C, C++, and Java! 


Only $399! (SCWPRO) 








pstring Untitled = “Untitled"; 

#if SystemSevenOrLater 
align word; 

unsigned integer noAutoCenter = 0x0000, 

centerMainScreen = 0x280a. 
alertPositionMainScreen = 0x300a. 
staggerMainScreen = 0x380a, 
centerParentWindow = 0xa80a, 
alertPositionParentWindow = OxbOOa. 
staggerParentWindow = 0xb80a, 
centerParentWindowScreen = 0x680a. 
alertPositionParentWindowScreen = 0x700a, 
staggerParentWindowScreen = 0x780a; 

#endif 

); 


RECT 

DWRD 

D00L 

BOOL 

DLNG 

DWRD 

PSTR 

AWRD 

HWRD 

BoundsRect 

ProcID 

Visible 

GoAway 

RefCon 

Items ID 

Title 

Auto Position 

ResEdit TMPL 

RECT 

BoundsRect 

Resorcerer TMPL 

WB12 

‘WDEF’ resource ID 


CASE 

Standard system*0 


CASE 

Standard desk accessory*! 


WB04 

Variation code 


CASE 

Document/standard accessory=0 


CASE 

Modal dialog=l 


CASE 

Plain frame"2 


CASE 

Shadow frame=3 


CASE 

Non-growable document=4 


CASE 

Moveable modal dialog=5 


CASE 

Zoomable document=8 


CASE 

No grow, zoomable document=12 


BOOL 

Visible 


BOOL 

GoAway 


DLNG 

RefCon 


RSID 

Item list (‘DITL’) resource ID 


ESTR 

Title 


HWRD 

Window placement 


CASE 

Leave it alone=$0000 


CASE 

Center on main screen=$280A 


CASE 

Center in parent window=$A80A 


CASE 

Center on parent’s screen=$680A 


CASE 

Alert on main screen*$300A 


CASE 

Alert in parent window=$B00A 


CASE 

Alert in parent’s screen=$700A 


CASE 

Stagger on main screen=$380A 


CASE 

Stagger in parent window=$B80A 


CASE 

Stagger on parent’s screen*$780A 




C struct 

//pragma options align=mac68k 


typedef struct { 


Rect 

boundsRect; 


short 

procID; 


char 

visible; 


char 

fillerl; 


char 

goAwayl'lag; 


char 

filier2; 


long 

refCon; 


Str255 

title; 


short 

positionCode; 


} WINDResource; 


//pragam options aligtrreset 



Note that the C struct is not an accurate description of the 
resource data format, because the size of the title in the resource 
data is variable, whereas in the above a fixed-length Str255 buffer 
of maximum size of 256 bytes has been declared. Because of this, 
you can’t cast the resource data handle to (WINDResource **) and 
expect the positionCode field to have the correct value in it. 


Also worth noting is that both the Resorcerer and Rez 
descriptions include symbolic definitions of various field 
constants of interest directly in the format declaration; whereas 
the ResEdit and C descriptions don’t. 

The Rez definition of a DLOG’ actually defines two data 
structures, depending on whether the constant 
SystemSevenOrLater is defined to be 1 or not. 

Creating a New Template 

To create a new template in Resorcerer, launch the resource 
editor, choose New File (CMD-N) and then choose New Resource 
(CMD-N) to specify the TMPL’. The resource ID can be 
anything; you can set the resource name to any four-character 
type you want the template to describe (for instance, ‘test’). This 
brings up Resorcerer’s Template Editor, which initally displays 
nothing since there are no fields defined yet in your new 
template. You can then choose New Field (CMD-N) from the 
editor’s Template menu (or double-click on the field insertion 
caret’s triangle) and enter the field data parsing type code and 
its label string. The field window provides you with a complete 
listing of all possible 4-character field types and their meanings, 
in case you’re not sure what the four-character code is. 

The Template Editor in Resorcerer displays and edits TMPL' 
resources (Figure 3); the Data Editor then uses the template to 
parse your resource as a data structure declared by the template 
(Figure 4). When a resource is selected in Resorcerer’s File 
Window, and the Data button is enabled, this means that a template 
for that resource type is available for the Data Editor to use. 
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Figure 4. The Data Editor uses a TMPL to edit an Ides ' resource. 
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Once you’re familiar with the various template field types 
and operation, it is usually easier to type the list of field types 
and labels into a text file and then copy and paste them all at 
once into the Template Editor’s window. You can do the reverse 
also: select any set of fields, choose Copy, and you can paste the 
template fields into a text file (Figure 5). 



Figure 5. Editing a TMPl as text. 


Resorcerer Template Field Types 

The template field types that Resorcerer supports can parse 
and format many categories of data. The newer types were 
defined over the years as needed, based on what developers, 
including myself, were doing in various resource data structures, 
or for ease-of-use interface reasons in the Data Editor’s 
operation, or for consistency. Since each “opcode” is allowed 
only 4 characters, it has been somewhat of a struggle to ensure 
some form of consistency in the type mnemonics. For instance, 
in general, an initial ‘B’ stands for “byte”, a ‘W’ stands for a 2-byte 
“word” (left-over from 68k terminology, not PPC terminology), 
and 1’ stands for a 4-byte long. ‘H’ stands for hex, ‘U’ for 
unsigned, ‘D’ for signed decimal, ‘P’ for Pascal, and ‘C for C 
(how succinct!). ‘S’ stands for some form of Sized. In the context 
of delimiting groups of fields, the suffix ‘B’ stands for “begin” and 
*E' stands for “end”. I have studiously avoided using any lower¬ 
case characters, as this would add a whole degree of freedom to 
the difficulty of remembering what code is what. 

In the following headings, the Resorcerer-specific extensions 
to the original ResEdit types are in boldface, and T’ve added some 
anecdotes explaining how some of these newer types came alxmt. 

Bits, bit fields, and boolean flags 

BBIT, WBIT, LBIT, BBnn, WBw?, LBnn, BFLG, WFLG, LFLG, BOOL 

The BBIT, WBIT, and LBIT fields each parse one bit out of 
the current byte, 2-byte word, or 4-byte long. Bits are parsed 
from most significant to least significant. Each of these is the 
same as a boolean field in a Rez template, but when Resorcerer’s 
Data Editor displays the data, it numbers the bits appropriately 
depending on die field type: 7 to 0 for BBITs, 15 to 0 for WBITs, 
and 31 to 0 for LBITs. The bit-numbering is reversed if little¬ 
ending parsing mode is in effect. 
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The BB nn, WB nn, and LBn/i fields operate similarly, except 
that instead of parsing just 1 bit, they each parse the next nn bits, 
where nn is a 2-digit ASCII decimal number encoded directly into 
the field type (sort of an immediate argument for the parsing 
opcode). Thus, WB01 is the same as WBIT; LB14 parses 14 bits 
from within a 32-bit long; etc. Each of these is the same as a 
boolean[] array in Rez. 

You can intermix the single-bit with multi-bit parsing fields 
in series, as long as the total number of bits always exactly 
reaches a byte, word, or long boundary, depending on whether 
you are using the ‘B...\ ‘W...’, or ‘L...’ variant. The Data Editor 
performs no implicit hidden padding in any way, and will 
complain if a multi-byte field crosses an appropriate storage 
boundary. For example, the two declarations 


Listing 2s Declar ations 

unsigned long sizeCode : 2, 

localChannel : 4. 
isExtinct : 1, 
isPurple : 1, 
isDinosaur : 1, 
isObnoxious : 1. 
groupCount : 21; 


Bits declared in C 


LB02 Size code 

LB04 Local channel 

LBIT Is extinct? 

LBTT Is a dinosaur? 

LBIT Is purple? 

LBIT Is obnoxious? 

LB21 Number of newsgroups 

LBIT Filler 


Bits in ResorcercrTMPL 


are basically the same, with the exception that in C the missing 
low-order bit is silently added by the compiler, whereas in a 
TMPL, you have to explicitly declare everything: the total number 
of consecutive ‘WB’ bits has to add up to a multiple of 16. 

I originally implemented the various word and long 
extensions to the BBIT field type because documentation for 
various bit flags routinely refers to them by bit number (e.g. bit 
24 in this long field), and I couldn’t stand sitting in front of multi¬ 
thousand dollar computing machine, forced to count bits in order 
to get things just right. 

The BFLG, WFLG, and LFLG fields are designed to correspond 
to how a single boolean flag has historically been coded in C, which 
is to say, as the value 0 or 1 stored in the low-order bit of a byte, 
short, or long integer. The higher order bits are parsed automatically 
by these three field types, but those bits are not editable and are set 
to 0. For instance, BFLG is the same as [BB07, BBITJ. 

The BOOL field actually parses 2 bytes. The value of the 
field is TRUE if it exactly matches the 16-bit value kept in 
Resorcerer’s own BOOL* 128 resource, which is set to 0x0100. 
The BOOL field type was implemented originally in ResEdit to 
take care of the hidden padding problem that occurs in C structS 
and Pascal records. Boolean fields are typed to be single bytes, 
but because of Lhis, the 68k compilers would add a hidden pad 
byte after the Boolean field. So a BOOL field is TRUE if its integer 
value is 236, and FALSE if it’s 0. I was never able to find any 
documentation on its behavior. After watching what ResEdit did, 


I chose to make the operation configurable with a ‘BOOL’ 
resource, since I wasn’t sure what it was supposed to do. You 
should try to avoid using this field type in favor of the more 
explicit bit types above. 

Decimal and hexadecimal integers, and resource IDs 
DBYT, DWRD, DLNG, UBYT, UWRD, ULNG, HBYT, HWRD, 
HLNG, RSID 

These instructions simply parse 8-bit, l6-bit, and 32-bit 
integer fields, depending on whether the field ends in ‘BYT’, 
‘WRD’, or ‘LNG\ The ‘D’ variants display and edit the data as 
signed decimal numbers; the Tf variants as unsigned decimal; 
and the ‘IT variants as unsigned hex. Parsing is subject to the 
current endian mode. 

Since storing the resource ID of some related resource as a 
2-byle integer is very common, Resorcerer has a special RSID 
field just for this purpose, allowing you to edit the related 
resource easily. The RSID field parses a 2-byte signed short 
integer, and displays it the same as a DWRD. But since the special 
field lets Resorcerer’s Data Editor know that the number is really 
a resource ID, the editor can let you quickly interactively link to 
(i.e. open with an editor) the referenced resource in the same 
file. To do this, though, it needs to figure out what the resource 
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type is, which it does in one of two ways. For instance, if your 
template field sequence contains the instructions 

Listing 3: Resource References 

Resource references in a template 

RSID Resource ID of new icon suite (‘ions’) 

TNAM Type of icon suite 
RSID Resource ID of icon suite 

then the Data Editor will be able to figure out which resource to 
open or create when you ask it to edit the referenced resource. 
With the first RSID field, the resource type to use is hardwired into 
the field’s label Oicns’). In the second RSID field, because there is 
no single-quoted type, the editor searches back in the data for the 
first TNAM field and takes that data as the resource type. 

Fixed-point numbers 
FIXD, FRAC, SFRC, FWID, FXYZ 

Fixed point numbers are integers whose bits are divided into 
two sets. The upper (more significant) set is the signed integral 
part of the number, and the lower (less significant) is the binary 
fractional part of the fixed-point number. The two parts of the 
number are separated by an implicit fixed decimal point. FIXD 
fields correspond the Mac Fixed data type [16.16]. FRAC fields are 
the same as the Mac Fract data type [2.301. SFRC fields are the 
same as SmallFract data types [0.16] used in certain color models. 
FWID (Font Width) fields are used in various font-related 
resources 14.121. Finally, FXYZ fields are used in some other color 
models [1.15]. All of these except the SFRC type display the data 
as signed fixed-point numbers. 

Floating-point numbers 
REAL, DOUB, EXTN, XT96, UNIV 

Standard IEEE 32-b it and 64-bit single- and double¬ 
precision floating point numbers get parsed by the REAL and 
DOUB field types. EXTN parses the 68k 80-bit SANE floating 
point numbers; XT96 parses the 96-bit extended SANE floating 
point values, and UNTV parses the old THINK C Universal format 
96-bit extended numbers. As far as PowerPC code is concerned, 
you only need to deal with REAL and DOUB floating point data. 

Resorcerer’s floating point support got added to the template 
system after developers working for a division of General Electric 
that sent balloons up into the atmosphere for data collection called 
saying they were keeping large amounts of floating point radar 
information in resources and needed to edit their data directly. 

Creation and modification times 
DATE, MDAT 

These two fields parse a 32-bit unsigned long number, and 
display it as the time and date as the system interprets it (number 
of seconds since Jan 1, 1904). Any MDAT field (modification date) 
is automatically adjusted to be the current time and date when 
you close the resource’s editing window after using the Data 
Editor to change any field in the resource. 


Script, language, and region codes 
SCPC, LNGC. RGNC 

Each of these parses a signed 2-byte integer, the same as a 
DWRD. However, when the editor displays the value, it 
automatically provides a popup menu from which to choose all 
the standard values for the various codes, so that you don’t have 
to remember or lookup which number stands for which 
language or region. These were implemented so that templates 
with these codes in them wouldn’t also have to have copies of 
the long list of CASE fields (see below) that normally would be 
used to build the popups. 

RGB colors and color tables 
COLR, CLUT 

The COLR field parses an RGB triplet: 3 2-byte integers, for 
the red, green, and blue color components, in that order. The 
Data Editor then displays the field in both numeric and graphic 
form, and you can change all three fields simultaneously using 
the system color picker. 

The CLUT field parses an entire Color Lookup Table data 
structure into one hex block. It was implemented to make it easier 
to parse embedded cluts in ‘PICT’ data as single hex blocks. 

QuickDraw Rectangles and Points 

RECT, PNT (the point field type ends in a space) 

The ‘PNT ’ field parses a pair of signed short QuickDraw' 
coordinate integers (vertical coordinate first), as in a Point data 
type. The RECT field does the same for Rect data types, and the 
Data Editor allows you to set the rectangle coordinates to new 
values graphically, using a marching ants marquee. If Lhe marquee 
is in front of and graphically contained within the content area of 
any other Resorcerer window, the coordinates recorded are 
converted to local coordinates for that window; otherwise, the 
values placed into the RECT field are in global screen coordinates. 

Alignment, pad, and filler bytes 

AWRD (= AL02), ALNG (= AL04), AL08, AL16, FBYT, FWRD, 
FLNG, Fnmm) 

Unlike C, Resorcerer (as well as Rez and ResEdit) templates 
perform no hidden data padding or alignment unless you explicitly 
declare it in the template. Given the myriad problems hidden 
alignment and padding causes developers, this is a good thing. 
However, it means that any data field, including numerical integers 
and floats, can occur at any byte offset, if you design the template 
that way (usually at some cost in efficiency, which on older 68000 
systems can run to a 100% loss when the machine crashes). 

The AWRD, ALNG, AL08, and AL16 fields allocate a variable 
number of 0 or more pad bytes so as to ensure that the following 
field will start on a byte boundary (as counted from the start of the 
resource data) divisible by the number 2, 4, 8, or 16 respectively. 

The FBYT, FWRD, FLNG, and Fnmm fields declare filler bytes 
of various fixed lengths (1, 2, 4, and 0 xnmm). Filler bytes are 
uneditable and generally set to 0. Filler bytes are typically used to 
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declare space within the data structure that will be used by code at 
runtime (for instance, to cache a Handle), but which has no 
meaning within the context of editing the resource data “offline”. 

ASCII characters, 4-byte literal type codes, and pure 
ASCII text 

CHAR, TNAM, TXTS, Tnmm 

The CHAR field type parses and displays a single-character 
ASCII byte. The TNAM (Type Name) field parses a 4-character 
ASCII literal. 

The TXTS field parses ASCII data until the end of the resource 
or until the end of an embedded, previously sized block of data 
within the resource. This field was implemented to fix the problem 
in the template distributed with ResEdit, which incorrectly declares 
a ‘TEXT’ resource as a null-byte terminated C string. 

The Tnmm field declares a fixed-length buffer of 0 xnmm 
bytes in which to expect 0 or more bytes of ASCII text. If the 
length of the text is less than 0 xnmm bytes, the remaining bytes 
are set to zero-valued pad bytes. 

Variable-length ASCII character strings 

PSTR (=BSTR), WSTR, LSTR, ESTR, PPST, OSTR, CSTR, 

ECST, OCST 

The PSTR field parses a Pascal-style string: a length byte 
followed by that many bytes of ASCII data. The WSTR field does 
the same, only the length is stored in a 2-byte integer; the LSTR 
field stores the length in a 4-byte long. 

The ESTR field (even-length string) also parses or creates a 
Pascal string, but if the length of the data (including the length 
byte) is odd, it appends an extra zero pad byte. At first glance 
this might appear the same as the sequence [PSTR, AWRDJ, but 
there is a subtle difference: it's the same only if the PSTR begins 
on an even byte offset to begin with. The OSTR field is the 
opposite of the ESTR field. It adds the pad byte to make the total 
Pascal string storage always an odd number of bytes and should 
only be used for parsing certain ancient resources. Similarly, the 
PPST field was implemented as a hack in order to be able to 
describe certain MPW resources whose data was stored ESTR 
style, except that the extra pad byte was incorrectly included in 
the length byte (which makes it impossible to tell whether it’s a 
pad byte or a data byte with value 0). 

The CSTR, ECST, and OCST fields are equivalent to the 
PSTR, ESTR, and OSTR fields, only they operate on arbitrary- 
lengthh, null-byte-terminated C-style strings, as opposed to 
initial-length-byte Pascal-style strings. 

Fixed-length ASCII character string buffers 
Pnmm, Cnmm 

These two fields each allocate a block of 0 xnmm bytes 
and interpret the clat a in the block as either a Pascal or C 
string, followed by as many zero-valued pad bytes as are 
needed to fill the block. 

The Pnmm field was designed to work in exactly the same 
way as all other Xnmm type fields: the field type declares a block 
of data of length Oxnmm bytes, and whatever gets stored in the 


block is interpreted according to X. Thus, the Cnmm, Fnmm, 
Hnmm, Pnmm, and Tnmm fields all indicate their sizes in exactly 
the same manner. I felt that consistency on this front was 
important. ResEdit interprets the Pnmm field differently, choosing 
to break consistency within the TMPL language in favor of 
making this one field conform to how such fields are declared in 
Pascal or C (sort of, since Str255 7 s aren’t declared as StrOEE’s). 

Resorcerer’s Data Editor therefore supports both 
interpretations, on th e assumption that developers almost never 
allocate an odd number of bytes for the fixed-length buffer. The 
editor checks all Pnmm fields and if it finds one where Oxnmm is 
odd (as it is in ResEdit for an even-length buffer), it will give the 
user the opportunity to use ResEdit-style parsing. 

Raw hex byte dumps 

BHEX, WHEX, LHEX, BSHX, WSHX, LSHX, Hnmm, 

HEXS, HEXD 

These fields parse and make editable blocks of bytes and 
present them as untyped hex data. With the first six types, the 
size of each block is taken from the initial byte, short, or long 
field. For instance, the BHEX field could be used to parse a 
Pascal string, only it would show the data in hex, not ASCII. 
The ‘SHX’ variants include the size of the size field in the count; 
the ‘HEX’ fields don’t. 

The HEXD field (Hex Dump), as originally defined in ResEdit, 
simply says take the rest of the resource data and edit it as untyped 
hex bytes. The HEXS field is similar, but is used for embedded hex 
dumps whose block sizes have been declared earlier. 

68K disassembled code dumps 
CODE 

This is the same as HEXD, except that it asks the hex editing 
display to show the data as disassembled 68K code as well as in hex. 

Automatically computed array repeat counts 
BCNT, WCNT (= OCNT), LCNT, ZCNT, LZCT, FCNT 

You can group a set of fields together and ask that the group 
be repeated until a condition is met. (In Rez, these are declared as 
arrays.) Usually this condition is given as an explicit repeat count in 
the data itself. The BCNT, WCNT, and LCNT fields each parse the 
count for the next repeated group of data fields, using an unsigned 
1-, 2-, or 4-byte integer count (byte, word, or long, respectively). 
The WCNT type is the same as ResEdit’s OCNT (one-based count) 
type. ZCNT (zero-based count) fields specify a 2-byte count that is 
1 less than the number of repeated items that follow\ The LZCT does 
the same, but stores the count (minus 1) in a 4-byte long. 

One important difference from ResEdit in how Resorcerer 
implements these counts is that in ResEdit, the count field has to 
immediately precede the start of the group of array item; in 
Resorcerer, as in Rez, the count can occur much earlier in the 
data, with intervening fields between the initial count and the 
array of repeated items. 

The FCNT (Fixed Count) field specifies a fixed-length count, 
where the count is not in the data at all, but taken from the field 
label string in the TMPL itself. 
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The BCNT field was originally implemented in order to 
build a TMPL for MPW Commando resources, as well as just 
plain generality. The FCNT field was first implemented for the 
benefit of parsing certain ColorSync resources. 

Groupings of fields into repeated array items 
LSTC. LSTZ, LSTS. LSTB, LSTE 

These “field” types don’t represent any data fields per se; 
rather, they declare the lx>unds of a subsequence of template 
instructions that represent a repeated item. You should use one 
of LSTC, LSTZ, LSTB, or LSTS to declare Lhe sLart of the group, 
and use LSTE to end it. 

LSTC starts a one-based counted list, whose count has 
previously been parsed from the data using any of the BCNT. 
WCNT, OCNT, or LCNT fields. The LSTZ field does the same 
thing, only the counted list is 0-based, meaning the count field 
contains one less than the number of items. I avoid 0-based lists 
whenever possible. 

lhe LSTB initiator says the list simply repeats indefinitely, 
without the Ixmefit of an initial count, until the end of the resource. 

The LSTS initiator says the list repeats until the number of 
bytes parsed reaches a previously declared size field’s value. 
This is called a Sized List as opposed to a Counted List. 

All of these list structures can nest. You can have an 
indefinite list of counted lists of sized lists, etc. 


Recursive templates for trees 
SELF 

You can describe simple recursive trees of similar items by 
using the SELF template field type as the sole field in a counted 
list group. A copy of the entire template’s set of fields will be used 
in place of the SELF field when you edit the data. Because the 
recursive list must be counted, there is no infinite recursive 
descent: the leaf lists in the tree must all have an item count of 0. 

Collections of common, required, key, or default values 
CASE 

Most data field types in a Resorcerer template can be 
followed by a set of 0 or more CASE instructions. These do not 
parse any actual data, but rather declare a set of named values 
that the previous field data can take on. They function similarly 
to an ‘enurrV or set of #defines\ In addition, the first CASE 
declaration in the list of CASE fields lets you install a non-zero 
initialization value into the data whenever you are creating a 
new resource, or new repeated item. 

As we will see in the next section, the set of CASE fields 
also declare the set of legal key values for a switched alternate 
record structure. 
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Integer keys for switch statements 

KBYT, KWRD, KLNG, KUBT, KUWD, KULG. KHBT. KHWD. 
KHLG, KRID 

In the more complex resource data formats, it often 
happens that a field’s value determines one of several alternate 
formats later in the data. The determining field is called the key, 
and the set of alternates formats are called the switched items. 
In Rez, such structures are described using a switch statement, 
and each alternate item is called a case. 

KBYT, KWRD, and KLNG each declare a signed 1-, 2-, or 4- 
byte integer whose value is to be used as a key to choose from 
amongst several alternate formats. 

KUBT, KUWD, and KULG are basically the same, only the 
key values are treated as unsigned decimal integers. 

KHBT, KHWD, and KHLG are again basically the same, only 
the Data Editor presents the key values as unsigned hex. These 
fields arc particularly useful in Resorcerer’s ‘PICT’ template, since 
the opcodes in a ‘PICT’ are all documented in Inside Mac using 
hex constants, not decimal, and each opcode is really a key 
value for alternate opcode data formats that follow. 

The declaration of the set of legal key values follows the 
keyed field type as the usual set of CASE fields. This allows the 
Data Editor to collect the symbolic descriptions of the cases into 
a popup menu in die usual manner, making interactive editing 
of the key field very easy. 

The KRID field is special: it does not declare a data field. 
Rather, it declares a pseudo-data field whose value is actually the 
current resource II) of the resource whose data the template is 
being used to edit. This makes it possible for the template to 
declare completely different data formats dependent solely on 
the resource ID (which is meta-information about the resource 
data) rather than on a previous key field in the data itself. The 
KRID field was originally implemented in order to deal with 
certain MPW and other older resources (‘PREC’s); however, its 
use is highly discouraged, since it obviates the reason for having 
a resource type attribute in the first place. 

Character and literal type keys for switch statements 
KCHR, KTYP 

These declare 1- and 4-byte ASCII character literals 
whose values are to be keyed off of. The KCHR field is the 
keyed version of the CHAR field; the KTYP field is the keyed 
version of the TNAM field (which is the same as an OSType or 
ResType or FourCharCode). 

Groupings of fields into alternate (keyed or switched) 
data structures 

KEYB, KEYE 

Following a key field and its set of n CASE declarations, there 
must be n alternate data formats, one for each CASE. The template 
field sequences describing each of these alternates must lx 
delimited by a KEYB...KEYE pair. The !al>el of the KEYB field must 
be the same as the character value of the earlier CASE declaration. 


Automatically 7 computed data sizes (in bytes) 

BSIZ, WSIZ, LSIZ. BSKP, WSKP, LSKP. SKPE 

Many data formats contain embedded sizes of sub-areas of 
the data. This is very important fo r desiging extensible formats, 
because they allow old code to traverse newer formats. The 
BSIZ, WSIZ, and LSIZ fields each store an unsigned byte count 
into a 8-, 16-, or 32-bit integer, respectively. The count stored is 
the number of bytes in the data, beginning at the first byte after 
the size field and continuing up to the next next matching SKPE 
field. The BSKP, WSKP, and LSKP fields are the same, except 
that the byte count they store includes their own sizes (e.g. an 
WSKP data field can never be less than 2 bytes). 

The SKP variants were originally implemented first, in order 
to edit balloon help resources. This flavor of size field allows the 
format parsing code to skip an internal data block by simply by 
adding the value of the field at that offset into the data to the 
offset itself to get to the first byte offset after this sized block of 
data. Consequently, I called these fields “skip offsets”, which is 
what the “SKP ’ pan of the field types derives from. The SKPE 
(Skip End) field doesn’t parse any data; it simply delineates 
where to stop counting bytes, and as such terminates the byte- 
counted area of the template for all 6 flavors of sizes. 

Data insertion and deletion 

+BYT, +WRD, +LNG, +nmm, +PST, +EST, +CST 

-BYT, -WRD, -LNG, -nmm, -PST, -EST, -CST 

Changing the structure that a template describes is as easy 
as inserting or deleting a field type using the Template Editor. 
Unfortunately, if you’ve already built resource data with the old 
template, the newly changed template won’t be able to parse the 
old data correctly. This problem becomes particularly acute 
when the changed template fields are part of any repeated or 
keyed items. How do you change the old data at the same time 
as the old template? 

The data insertion and deletion fields help you solve this 
problem. The insertion field types all begin with the *+’ 
character; the deletion fields all begin with a *-\ An insertion 
field in a template tells the Data Editor to create the field when 
the old data is opened for editing, and to leave the data there 
when closing the resource. The deletion fields work exactly 
oppositely. It parses the old data field normally when you open 
the resource, but deletes the field when you close it. If an 
insertion or deletion field is part of a repeated item, it will do its 
work on every item in an existing array in a resource. 

As usual, the ‘BYT’, WRD’, and ‘LNG’ fields operate on 1-, 
2-, and 4-byte fields; the l nmm ’ field operates on 0 xnmm bytes. 
The ‘PST’ fields insert or delete a Pascal string; the CST’ fields 
do the same for C strings; and the ‘EST’ fields insert or delete 
even-Pascal strings (as declared by the ‘ESTR field). 

Once you’ve changed the data to insert or delete fields, 
though, you have to remember to go back into the template 
and either remove any of the deletion fields, or change any 
of the insertion fields to the non-insertion equivalents, before 
opening the resource data again. You don’t want to make the 
changes twice! 
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Template comments 
DVDR 

You can place a DVDR field anywhere in the TMPL field 
sequence. It doesn’t parse any data, and its label string serves as 
a comment that the Data Editor draws for you on the right side 
of the data display. 

Endian parsing mode 
BNDN. LNDN. BIGE, LTLE 

Templates default to parsing multi-byte numerical fields in 
big-endian style, since this is standard on the Mae. However, you 
can change the current endian interpretation to little-endian by 
using the LNDN or LTLE fields (which don’t parse any data). The 
variants that end in "NDN” are invisible in the data editor display; 
the variants that end in “E” are shown. 

Data pre- and post processing with code plug-in filters 
FLTR 

Data formats can be arbitrarily complex, and it’s quite 
easy to design a format that the simple parsing fields 
available in the TMPL “language” can’t parse. Typically, any 
parts of the data format that depend algorithmically on other parts 
of the data can’t be properly edited by a TMPL. Typical 


examples include encrypted or compressed data; fields 
whose values are arithmetic formulas dependent on other 
fields (e.g. rowBytes in a PixMap); checksums; etc. 

If the first field in a TMPL is FLTR, the template is considered 
a filtered template. This means that a code resource of type ‘FLTR' 
should accompany the template in the same file as the TMPL 
resource was found. The Data Editor will call the code resource 
to filter the data both on input to the TMPL parsing mechanism, 
and on output. Thus the FLTR code converts the initial I Iandle of 
data into an intermediate form that the TMPL describes. On 
output, the FLTR unconverts the data the TMPL describes, creating 
a I Iandle of data in its final form. 

Summary 

Resorcerer’s TMPL language, which is a superset of ResEdit’s, 
lets you easily describe and then interactively edit many different 
resource formats. Quite often, there is a one-to-one mapping from a 
Rez template to a Resorcerer template. Resorcerer is shipped with a 
great many templates for common Mac system and application 
resources that Apple engineers have designed using Rez. 

A concise listing of all these template field types can be 
found at <http://www.mathemaesthetics.com/ResTemplates.html>. 
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Making Your Application Run Well in a 
Multiscript Environment 


A few techniques that wiU 
give your application polish 
on International systems 


Introduction 

Many applications are sold in the U.S. 
and Europe without any major changes to 
their codebases for a specific country’ or 
region. Sometimes this means that the non- 
U.S. tiser ains into oddities of design or 
implementation that aren’t quite right for his 
or her language or region, because the code 
assumes a U.S.-centric design. Using for 
the thousands separator in a number field, or 
7” for a short date separator in a date are two 
examples. These defects are not that serious, 
and in fact are avoidable if the program uses 
the Mac OS International Utilities functions to 
extract region-specific data from resources in 
the System, like the correct thousands 
separator or date separator. 

Once the product is to be distributed 
in a region which uses a different script 
system from that in the U.S., things can get 
a bit more complicated. The U.S. uses the 
Roman script system to display text and 
other data, as does most of Europe. Japan, 
however, uses the Japanese script system 
to display text and other data, and 
therefore some products that assume 
Roman script behavior will not function 
properly, or worse, will not function at all. 


This article will illustrate some techniques you can use in 
your application so it will run properly in a multi-script 
environment. These techniques allow your code to be easily 
localizable into any language in any script system, which will 
increase your possible user base and therefore your product’s 
revenue potential. 


What is 'Mojibake?* 

Mojibake Cmoh-jee-bah-keh”) is a Japanese word for when a 
run of text is displayed in the wrong script system, and produces 
garbage characters that don’t make any sense. An example is below: 

Text in correct (Japanese) font Text in wrong (Roman) font 

i‘5eoa a C0 

Figure 1. Mojibake Example. 

This problem is one of the most common with applications 
that support multiple fonts. What has happened is that each byte 
in the text stream above has not changed, but the font used to 
render it has. This problem is a side-effect of the way in which 
the Mac OS supports so many languages, by grouping languages 
and their fonts into script systems. A run of the same raw text 
data will effectively change its meaning (or lose it completely) 
depending on which font is used to display it. 

This means that unless the application makes an effort to 
protect the user from mojibake , it will likely happen, and this is 
a bad thing. The user may think that their data has become 
corrupted, and may panic, telling all his or her friends how 
buggy your software is. 

It turns out that protecting the user from mojibake is not 
such a big deal. It can be easily defined and scoped so you will 
always know what the ‘right’ thing is to do when you are 
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handling text in multiple fonts in a multiscript environment. For 
example, you only need to worry about mojibake when: 

• The user’s system has more than one script system installed. 

• There are characters in the Extended ASCII (hi-ASCII) range 
(> ASCII 127) in the text. 

Further, there are four possible situations in which mojibake 
can occur: 

A. When the user chooses a keyscript different from the script 
of the current font and begins to type hi-ASCTI characters. 

B. When the user selects text and chooses a font from a 
different script than the text’s current font AND there are hi- 
ASCII characters in the selection. 

C. When there is hi-ASCII in the text of the user interface of 
your application and you default to drawing it in a font that 
can change (i.e. the appFond) depending on the main script 
of the system. 

D. When you are importing text without font infonnation and must 
set the font yourself to some default, e.g. plain text import, or 
opening a document with fonts not installed in the current 
system AND there is hi-ASCII in the text stream being imported. 

Notice that in all four of those cases there is a common 
attribute: Hi-ASCII text. All fonts in all scripts (except for special 
fonts in the Roman script, like Symbol) share the same lo-ASCII 
characters, but have different hi-ASCII characters depending on 
the script of the font. There are some exceptions to this when a 
country has a standard different from the ASCII standard for 
character codes 0-127, but for most purposes you as the 
application developer can assume that if the character code is 
<=127 and it is not part of a multi-byte character, it will display 
the same glyph no matter what font you are in. This is a 
powerful piece of information, because it will guide how you 
implement several of the features mentioned in this article. 

Font Input Locking 

This feature protects the user from mojibake as they are 
inputting text, as in situation A, above. The desired behavior in 
that case is if the user is typing in a keyscript that is different 
from the script of the insertion font, then you must temporarily 
“lock” the font to a font from the same script as the keyscript. 
This font can be a user preference, or you can simply use the 
appFond or sysFond for that script. 

Most applications that have word-processing functionality 
buffer the text as it is typed in, to maximize typing efficiency. 
This means you have a tight loop that repeatedly gets keyDown 
events off the event queue and stores the resulting text in a 
buffer. When the user is using an Input Method program to type 
in Japanese, once they hit the return key to send to text to your 
application, you will get a whole stream of keyDown events in 
rapid succession, each keyDown representing a byte in the 
stream of 2-byte characters. Once you buffer the characters, you 


would insert the text from that buffer into the document as a 
chunk into the current stylerun, which has a font attribute. It is 
the font attribute that concerns us here. Sometimes the text 
being inserted will be incompatible with the current insertion 
font, and you will have to create a new stylerun with a font that 
will render the text properly. 

Session-based Font Input Ix>cking 

Session-based Font Input Locking is appropriate when the 
user is typing in a non-Roman keyscript, where all the characters 
will be hi-ASCII, or multibyte characters which mix hi-ASCII and 
lo-ASCII together. In that case, all the incoming characters will 
need to be “locked” to a font from the same script as the 
keyscript. As soon as the user switches to a different keyscript, 
you can restore the old insertion font. 

Character-based Font Input Locking 

Sometimes you only want to “lock” the font of some of the 
characters in the buffer, leaving the others in the insertion font. 
Tliis is the case when the user is typing in the Roman keyscript, 
but the insertion font is non-Roman. Most of the characters will 
be lo-ASCII, but the user can also hold the option key down and 
Lype a single hi-ASCII character, which will need to be “font 
locked” to a Roman font to display the proper glyph. In this 
case, only that hi-ASCII character needs to be in its own stylerun, 
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and you can restore the original insertion font when the user 
types the next lo-ASCII character. (See Figure 2). Another case 
where Character-based Font Input Locking is appropriate is 
when the user is typing in the Japanese keyscript in a Roman 
font am, but using the single-byte input mode of their Input 
Method, resulting in lo-ASCII characters that do not need to be 
font locked. However, as soon as the user switches to a mode 
which allows input of single-byte hi-ASCII or 2-byte characters, 
you will need to lock those characters to a Japanese font. At all 
times during this input session, the keyscript will be Japanese, 
so you cannot assume all text input in Japanese keyscript needs 
font locking when in a Roman font. 

Text is typed in a Japanese font Hi-ASCJI ‘g'is font locked 

to a Roman font 

Fran'/Sis Francais 

Figure 2. Character-based Font Input lucking. 

When organizing your code to support font input locking, 
it helps to break down the problem into separate parts of 
filtering for hi-ASCII (either in a text buffer or as keyDown 
events), and creating new styleruns for text that needs to be font 
locked. The following code (Listing 1 and Listing 2) are simple 
examples of how to do this. 

Listing 1: Finding Hi-ASCII Characters in a Buffer 


} 

return index; 


ExtendStyleRun 

/* When extending the length of the current stylemn, all styleruns following it must 
have their startPos member incremented so they match up with the text. 7 

void ExtendStyleRun(StyleRun “ styles, long numStyles, 
long index, long amount) 

( 

++i ndex ; // the next style has the start we need to 
// increment 

while (index < numStyles) 

(‘styles)[index++].startPos += amount; 

1 


AddNewStyleRun 

f* Adding styleruns to your text is at the core of font locking functionality. All styleruns 
are stored in a Handle, and are in order according to text order. You must bump the size 
of the Handle and then insert your new style in at the appropriate place. 7 

Boolean AddNewStyleRun(StyleRun * * styles, long * numStyles. 

long index, * newStyle, 
long runLength) 
l 

// First try to increase the stylerun array handle 

if (SetHandleSize((Handle)styles. 

GetllandleSize ((Handle) styles) + 
sizeof(StyleRun)) 

{ 

//Then make room for the new stylerun in the array 

BlockMove((Ptr)&(*styles)[index], 

(Ptr)&(*styles)[index + 1], 

sizeof(StyleRun) * (‘numStyles - index)): 

//The copy in the new stylerun into the array 

BlockMove((Ptr)newStyle. (Ptr)&(‘styles)[index]. 
sizeof(StyleRun)); 

// increment size of array handle and index 

(*numStyles)++; 


BufferHasHiASCn 

T Loop through a buffer and stop when you find a hi-ASCII character. 7 

Boolean BufferHasHiASCII(uchar ‘ buffer, long length) 
long index; 

for (index = 0; index < length; index++) 

I 

if (buffer[index] & 0x80) 
return TRUE; 

I 

return FALSE; 


Listing 2: StyleRun Management Sample 


FindStylcRunlndex 

r Each StyleRun structure has a starting character position (startPos) and a font 
attribute. You would also have size, face, etc. in a real application. 7 

typedef struct tagStyleRun l 
long startPos; 
short font; 

1 StyleRun; 


// (iiven an ordered array of SlylcRun structures, 

// find the one that 
// corresponds to the given charPos. 

long FindStyleRunIndex(StyleRun “ styles, 
long charPos) 


long numStyles, 


long index: 


for (index = 0; index < numStyles; index-H-) 

I 

if ((‘styles)[index].startPos <= charPos) 
break: 


// Increment start positions of each run after 
// the new run 

ExtendStyleRun(styles, ‘numStyles. index, runLength); 
return TRUE; 

1 

else 

return FALSE; 


Now let’s put these things to use. Say you have a 
function that creates a buffer of text as the user is typing, and 
when the user is done, you process it for font locking, add it 
to the document’s data, and then draw it onscreen. Note that 
much of this code is over-simplified to illustrate the concepts 
in this article; you should improve upon it before using it in 
a real application. 

Listing 3 shows how to make a keyDown loop that gets keys 
until the user stops typing rapidly or they change the keyscript: 

Listing 3: Fast Key Loop to Make Key Event Buffer 

DoKey 

T Loop until no more keyDown events or until keyscript changes. 7 

void DoKey(Str255 buffer, ScriptCode * keyScript) 

EventRecord theEvent; 
uchar char; 

‘keyScript * GetScript.ManagerVariable(smKeyScript); 
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while (EventAvail(keyDownMask, &theEvent)) 

{ 

if (buffer[OJ < 255 && 

*keyScript ~ GetScriptManagerVariable(sraKeyScript)) 

{ 

(void)GetNextEvent(keyDownMask, fctheEvent); 
char * (uchar)(theEvent.message & charCodeMask); 
buffer[buffer[0]++] = char; 

) 

else 

break; 

1 

) 


Listing 4 shows how to take the buffer and keyscript 
information from Listing 3, and perform Font Input Locking 
before adding the typed text to your document: 

Listing 4: Font Input Locking 


PrcxressKeyDownWithFontLocking 

/* Actually perform Font Input Locking using the functions introduced earlier 7 


StyleRun ** gStyles; // stylcruns in text 

long gNumStyles; 

uchar ** gText; //textdata 

long gTextLength; 

long gCurCharPos; // where we are in the text 


Boolean ProcessKeyDownWithFontLocking(Str255 buffer. 

ScriplCode keyScript) 


( 


Boolean 

ScriplCode 

long 

StyleRun * 

StyleRun 

short 

long 

long 


fontLocked = FALSE; 
fontScript; 

curStylelndex = GetStyleRunIndex(gStyles, 

gNumStyles, gCurCharPos); 

curStylePtr; 
newStyle; 

curFont, goodFont; 

lastRunLength = buffer[Oj; 

index. subRunStart, subRunLength = OL; 


//Add the text buffer to our text data handle... 
if (SetHandleSize((Handle)gText. 

GetHandleSize((Handle)gText) + 
(long)buffer[0])) 

{ 

BlockMove((Ptr)&(*gText)[gCurCharPos], 

(Ptr)&(*gText)[gCurCharPos + bufferfO]], 
gTextLength - gCurCharPos); 

BlockMove((Ptr)&buffer Til. (Ptr)&(*gText)[gCurCharPos]. 

(long)buffer[0]); 
gTextLength += buffer[0]; 

} 

else 

return FALSE; 
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// loop thru sub-runs in buffer 

for (index = 1; index <“ (long)buf fer [0] : index++) 
( 

// find first sub-run that needs font locking 

subRunStart = index; 

while (index <= (long)buffer[0] && 

!(buffer[index] & 0x80)) 
index++; 

// if lo-ASCII starts buffer, extend current 
// stylerun by amount of lo-ASCII characters 

if (!(buffer[subRunStart] & 0x80)) 
ExtendStyleRun(gStyles. gNumStyles, 

curStylelndex, index - subRunStart); 
curStyleIndex++; 

newStyle.startPos += index; 
newStyle.font = goodFont; 


// If more than one script system is installed 
// and we have hi-ASCIl 

// we need to make new style runs for each ‘locked’ run 

if (GetScriptManagerVariable(smEnabled) > 1 && 

BufferHasHIASCII((uchar *)&buffer[1], (long)buffer[01)) 

{ 

curStylePtr = &((*gStyles)[curStylelndex]); 
curFont = curStylePtr->font; 
fontScript • FontToScript(curFont); 

// make stylcruns for hi-ASCII and 2-byte chars in rim 

if (keyScript !- fontScript) 

l 

BlockMove((Ptr)curStylePtr, (Ptr)&newStyle, 
sizeof(StyleRun)); 

goodFont “ GetScriptVariable(keyScript, 
smScriptAppFond); 


// Find length of run that needs locking 

while (((buffer[index] & 0x80) | 

CharacterByteType((Ptr)&buffer|1], index, 
keyScript) != smSingleByte)) && 
index <= buffer[01) 

{ 

index-H-; 

subRunLength++; 

) 

AddNewStyle(gStyles, SgNumStyles, curStylelndex. 

&newStyle. subRunLength); 
lastRunLength = subRunLength; 
subRunLength = 0; 

) 

fontLocked = TRUE; 

1 

1 


September 1998 • MacTecii 


Making Your Application Run Well tn a 
Multiscript Environment 


41 

























// Increment all stylcruns’ indices after the current one. 

ExtendStyleRun(gStyles, gNumStyles. curStylelndex, 
lastRunLength); 

return fontLoeked; 

) 


Font Change Locking 

Font Change Locking is the term for when the user chooses 
a new font for a selected run of text, but some of the text in the 
run is hi-ASCII and in a font from a different script than the 
chosen font, so that text is not changed to the new font. This 
remedies mojibake in situation B. 

User selects text in a Roman font User chooses a Japanese font 


El Nino 


Figure 3• Mojibake Without Font Change Locking. 

User selects text in a Roman font User chooses a Japanese font 


El Nino El Nino 


Figure 4. Font Change Locking jocks’ the ‘n’ to a Roman font. 
The basic Font Change Locking algorithm is: 

• Check if font(s) in selection are of a different script than the 
chosen font. 

• If so, check if there are any hi-ASCII or multibyte characters 
in the selection. 

• If there are, create new stylemns for each run of “locked” 
characters. 

• Change the font of all characters that are not “locked” to the 
chosen font. 

Always allow the user to turn Font Change Locking off and 
force the font to be whatever they set it to, perhaps by holding 
down a modifier key when they choose a font. This is useful 
when you import a large amount of raw text data and can’t be 
sure which script system is appropriate to display the text in. You 
may guess wrong, in which case the user will have to force-set 
the font to be the proper one. 

Font Menu - Keyboard Synchronization 

This feature prevents mojibake by automatically setting the 
keyscript to a script compatible with the font the user selects, 
when there is no text selection. Here is the basic algorithm when 
the user chooses a new font from the Font menu: 


• Check if there is no text selection (insertion point is flashing). 

• If so, check if the current keyscript is non-Roman. 

• If so, check if the script of the font chosen is different from 
the keyscript. 

• If so, change the keyscript to that of the chosen font. 

This is not the same as changing the current keyscript based 
on where the user clicks in multiscript text, sometimes called 
“Font-Keyboard Synchronization.” That is not recommended to 
be a default behavior, and if you implement a feature like that, 
you should make it a user preference. 

Sorting the Font Menu 

You should sort all fonts in your font menu according to 
their script, but how you order the scripts is up to you. There is 
one thing that you should consider: 

Sort the script of the application’s user interface translation 
first, i.e. if the HI is in English or French or some other Roman 
script language, then the Roman script fonts should be at the top 
of the Font menu. If the UI is in Japanese, then the Japanese 
fonts should be at the top. This is because the user is most likely 
to use the language of the UI localization in their documents, and 
they need those fonts to be the most accessible, i.e. users of 
French ClarisWorks will want fonts that can be used in French 
text at the top; users of Japanese ClarisWorks want the Japanese 
fonts at the top. Note that the UI localization script can be 
different from the System script, which is always sorted first by 
the system. After placing the localization script’s fonts first, you 
can use the Mac OS API ScriptOrder() to figure out which scripts 
should come before which others. 

Support of Underline in 2-byte Fonts 

QuickDraw on the current version (8.1) of Mac OS does not 
support underline on fonts from the Japanese, Simplified Chinese, 
Traditional Chinese, or Korean scripts. This is because QuickDraw 
draws its underline at the baseline of the glyph, according to the 
measurements in the font’s fontMetrics record. The baseline on 2- 
byte glyphs in fonts from the unsupported scripts falls on top of 
part of the character, so instead of drawing the underline lower, 
QuickDraw bails on drawing the underline at all. 

In Figure 5, two characters are drawn in a Japanese font 
(Heisei Mincho 72 pt) and a comparative character is drawn next 
to them in a Roman font (Palatino 72 pt). The ‘M’ in Palatino font 
has QuickDraw underline applied, and that line is extended 
backwards underneath the two Heisei Mincho font characters. As 
you can see, the QuickDraw underline would have obscured part 
of the 2-byte character. The second underline has been drawn 
further down in the descent area of the font, and is consistent 
with underline placement of other Japanese applications. That is 
the line your application would draw. 
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Figure 5. Comparing 2-byte Baseline to “Correct” 
Underline Position. 


In some fonts, like Osaka (the appFond and sysFond of the 
Japanese version of Mac OS), the underline may appear to be a 
little far from the characters if placed in the middle of the descent 
area, but most Japanese fonts do not have so large a descent 
value as Osaka, so the line ends up much closer to the text for 
a more natural look. Of course, the best solution would be for 
Japanese and other 2-byte fonts to have a special adornment 
table that told the application where best to draw the underline. 
Using the baseline for both underline location and placement of 
1-byte Roman glyphs does not work in a 2-byte font. 

Here is some sample code that draw r s the underline 50% into 
the descent area of the font if QuickDraw will not draw the 
underline for you. It assumes the port has already been set up 
with the correct font and pen size for drawing underlines. 

Listing 5: Drawing Your Own Underline 


DrawUnderlincdTcxl 

void DrawUnderlinedText(Ptr textPtr, short offset. 

short length) 

{ 

Point ptl, pt2; 

FMetricRec fontMetrics; 

ScriptCode script = FontScript (); 

TextFace(underline) ; // for fonts that are supported 

GetPen(&ptl); 

DrawText(textPtr, offset, length): 

CetPen(&pt2); 

if (script =~ smJapanese || script = smTradChinesc | 
script — smSirapChinese || script = smKorean) 

I 

FontMetrics(^fontMetrics); 

MoveTo(ptl.h. ptl.v + fontMetrics.descent >> 17): 

Line(pt2.h - ptl.h, 0); 

MoveTo (pt 2. h, p 12. v): // restore pen location 

I 

} 


In a future version of the system software, it has been said 
that QuickDraw will finally support drawing underline on 
Japanese and other 2-byte fonts as a user preference. 

Truncating Strings 

String truncation has been made very simple with the new 
Mac OS APIs TruncString() and TruncText(). These functions are 
used for strings or text that appear in your user interface w r here 
the main reason for truncation is that the string may not fit in the 
given pixel width. However, sometimes you don't care about the 
pixel width of the text, but you want to make sure you don’t cut 
text off in the middle of a 2-byte character boundary. 


The function below takes a string and a desired truncation 
length and a script, and truncates the string on the nearest 
character boundary less than or equal to the truncation length. 


Listing 6: Multibyte-safe String Truncation 

Smart TmncateString 


void 

( 

if 

l 

) 


SmartTruncateString(Str255 string, uchar truncLen, 
ScriptCode script) 

(CharacterByteType((Ptr)&string[l 1. (short)truncLen. 

script) = smFirstByte) 

string[0] “ truncLen - 1; 


else 

string[Oj = truncLen: 

1 


Searching WorldScript Text 

Most search algorithms do a straight byte-compare of text 
and do not look at script information. This will not produce 
correct resulLs for the same reason that mojibake occurs: Text 
will change meaning depending on what font (script) it is 
displayed in. Therefore, you should put an additional check on 
a found text run to make sure it is the same meaning (script) as 
the search string. You can use the International Text Utilities 
functions CompareStringO, CompareText(), etc., but the behavior 
of these functions may not always be what you want (for 
example, sometimes diacritical marks are ignored, making the 
strings “Rose” and “rose” return equality), and they require the 
use of a ‘itl2’ sorting resource to do most of the work. 

In the following function, you pass a search string (from a 
Find dialog, for example) and script information for that string, 
and a text buffer with style information (from the body of your 
document, for example). The function does a byte compare first, 
then if the style information and script information are not NULL, 
it takes them into account and remrns TRUE if the search string 
has been found, and returns the offset into the text buffer at 
which the string was found in a parameter. 

Listing 6: WorldScript-sawy Byte Compare 


Smart BytcCompare 

Boolean SmartByteCompare(Str255 searchStr, ScriptCode script, 
uchar * * textBuffer, long length, 

StyleRun ** styles, long numStyles, 
long * foundOffset) 

I 

Boolean found * FALSE; 
uchar indexl; 

long index2; 

*foundOffset = -1L; 

for (index2 = 0; index2 < length; index2++) 

1 

for (indexl = 1; indexl <= searchStr [0] ; indexl++) 

t 

if (searchStr[indexl] != textBuffer[index2]) 
break: 
else 

index2-B-; 

) 
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if (indexl = searchStr[0]) 


( 

found - TRUE; 
break; 

} 

) 

// Now check the script of the stylcnin of the found text. 

// In real life, you’d also check if the found text crossed 
// multiple styleruns and check each of them for the 
// script. 

//Also, you would continue searching if the first found 
// result 

// turned out not to be the same script as the search 
// string. 

if (found == TRUE && styles != NULL) 

( 

long stylelndex; 
short font; 

stylelndex - FindStyleRunlndex(styles. numStyles, 

index?. - indexl); 

font " ('styles)[stylelndex].font; 
if (script !“ FontToScript(font)) 
found = FALSE; 

1 

return found; 


Conclusion 

We have examined a few ways you can make your 
application run lietter in multiscript systems right out of the box, 
with no additional localization. Protecting the user from garbage 
characters, or mojibake as it’s known in Japanese, is something 
every application should try to do, even if it is only being sold 
in a particular locale. Every technique explained in this article 
revolves around making your code become script-aware , that is, 
always to pass script information along with any text you may 
be manipulating internally in your application. If text has a font, 
it has a script. When there are multiple script systems installed 
on the user’s system, you want your application to behave just 
as gracefully as when there is only a single script installed. 
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NetProLive — 

“The Web Site** 

Like the magazine, NetProLive 
the web site, will feature 
content for web developers 
and network administrators. 
Although selected material 
from NetProfessional magazine 
will appear on the site, it 
won't be just a static set of 
archives, but rather a 
dynamic set of pages. 

NetProLive also contains 
industry news links to 
support resources such as 
mailing lists, community 
resources like User Groups 
and Professional Associations 
for web developers and 
network administrators, and 
much more. 



http://www.netprolive.com 
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Rez is Your Friend 


What is Rez and why 
should / care? 


What is Rf.z? 

Every Macintosh program is made up 
of resources. Dialogs, Alerts, String Lists, the 
list goes on and on. These resources have to 
be created by the someone, and are part of 
the program. Every programmer is familiar 
with ResEdit or Resorcerer, which let you 
edit resources visually. Fewer programmers 
know about Rez, the resource compiler. 

Rez is a compiler, like a C, Pascal or 
C++ compiler. It lakes text files (usually 
with the suffix \r’ ) as input, and 
produces a resource file as output. MPW 
also ships with DeRez, which takes a 
resource file and produces a text file that 
can be input back into Rez. Originally, 
Rez ran only under MPW, but both 
Symantec and Metrowerks have shipped 
versions of Rez as part of their integrated 
development environments. 

In this article, I’m not going to give a 
tutorial on Rez. Instead, I’m going to 
concentrate on the reasons that you should 
be using Rez to manage your resources. A 
full manual for Rez (and DeRez) can be 
found in Appendix C of “Building and 
Managing Programs in MPW, available at 
<ftp://ftp.apple.com/devworld/Tool_Chest/Core_M 
ac_OS_Tools/MPW_etc./Documentation/MPW_Ref 
erence/Bldg%26Mng_Progs_ln_MPW.sit.hqx>. 


A Little History 

When first Macintosh development environments shipped 
(back in 1985), they included a tool called RMaker. (ResEdit 
didn’t appear unlil late 1985 or early 1986) RMaker (short for 
Resource Maker), like Rez, was a resource compiler, translating a 
text file into a resource file. However, RMaker knew about only 
a few resource types, and was not easily extensible. So, when 
Apple shipped MPW 1.0 in 1986, they provided a completely 
new set of resource tools. Rez, DeRez, and RezDet. Joel West 
wrote an article for this magazine about the new tools in MPW 
l .0. See <http://www.mactech.eom/articles/mactechA/ol.03/03.02/Rez- 
ervations/text.htmb for a description of those tools as they 
appeared in MPW 1.0. 

An improved version of Rez shipped with MPW 2.0 in 1988, 
and Rez 3 0 included support for QuickDraw' pictures. 

Symantec shipped stand-alone versions of Rez and DeRez 
(cunningly named SA-Rez and SA-DeRez) with Think C 6, and 
incorporated Rez into the TDF. with the THINK Project Manager 
7.0 (68K) and the Symantec Project Manager (PPG). 

Metrowerks incorporated Rez into their IDE starting with 
Code Warrior 6. 


Why Rez? 

At this point you are probably asking yourself, “Why 
should 1 care about Rez? I do all my resource editing in 
ResEdit/Resorcerer, why would anyone use Rez?”. There are 
several reasons: 

Comments 

Since Rez source files are text files, they can contain comments 
about why a resource contains some information. A change history 
is another good tiling to put here. Unless you have a great memory, 
you will want to put comments in your resource files so that when 
you look back a year (or two later), you can tell why this number 


Marshall Clow is a programmer. He has worked for Palomar Software, Hewlett-Packard, and Aladdin Systems. Among other 
things, he has written PICT Detective, Aladdin’s Resource Compression Toolkit, and way too many resource processing tools. 
He currently works for Adobe Systems, where his title is “Bad Influence". When he’s not coding, he can be found mountain 
biking or checking out micro breweries. He can be reached at <mclo w@mailhost2.csusm.edu> 
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in a table was changed from a 23 to a 42. Since resource files are 
binary data, there is no place to put comments there. 

Don’t underestimate the importance of comments. Would 
you write code without comments? They have saved me hours 
(or days!) of debugging on many occasions. 


Macros 

This is a big feature. Since Rez supports C-style macro 
processing, you can give symbolic names to your resource types 
and IDs, and use these definitions in a header file for both your 
resources and your C/C++ code. Whenever I see a bit of code 
that says something like: 

h = GetlResource ( ‘Foo!', 234 ); 

I cringe. I just know that somewhere down the line, someone 
will need to change the ID of that resource, and they may or 
may not find all the places that load/use that resource. 1 use a 
header file that is shared between my resource files and my 
source files. 

// File Foo.h 

//define kNormalFooResID 
// File Foo.c 

h = GetlResource ( ‘Foo!’, kNormalFooResID ): 

// File Foo.r 

resource ‘Foo!’ ( kNormalFooResID, purgeable ) ( 


If you prefer a less made-up example, here’s one that uses 
familiar resource types: 

// File Foo.h 

//define kNoAppleEventsAlert 130 
// File Foo.c 

if (( Gestalt( gestaltAppleEventsAttr, &attrs )) 1= noErr ) 
Alert ( kNoAppleEventsAlert, nil ); 
else ( // normal processing 

// File Foo.r 

resource 'ALRT’ ( kNoAppleEventsAlert ) { 

{ 0, 0, 200, 400 1, //bounds for the alert 
kNoAppleEventsAlert, // the Dm. associated with this alert 

( //Alert Stages 

OK, visible, silent, 

OK, visible, silent. 

OK, visible, silent. 

OK, visible, silent 

). 

centerMainScreen //Where to show the alert 
): 

resource 'DITL* ( kNoAppleEventsAlert ) { 

// Dialog items go here 

); 

To renumber the alert, all I have to do is change one line in 
Foo.h and rebuild. The resources will be renurnlx^red automatically, 
even the reference to the D1TL inside the ALRT resource. 

Not convinced yet? Here’s another example. Suppose that 
you want all the buttons in your application to have the same 
“look”. For the sake of argument, let’s say that you want them 
all to have the same height. Using ResEdit or Resorcerer, this is 
a nightmare, because you would have to go through each and 


every dialog and find each button, and check (and possibly 
change) the height of each button, to conform to your standard. 
Heaven help you if some UI designer or product manager 
decides that all the buttons need to be two pixels higher (to aid 
in translation to Urdu, no doubt). 

Using Rez, (and a little foresight), it’s a one line change! 

// File Foo.h 

//define kButtonHeight 20 
// File Foot 

resource ‘ALRT* ( kNoAppleEventsAlert ) 1 
// We’ve seen this before. 

1 : 

resource 'DITL’ ( kNoAppleEventsAlert ) {( 

1260. 129. 260 + kButtonHeight, 2091, 

Button ( enabled. “OK” }; 

1260, 40, 260 + kButtonHeight, 120), 

Button { enabled, “Cancel" ); 

(8. 72, 23, 264), StaticText I disabled. "Hi Mom!" }; 

1 ; 

1 ; 

When I change the kButtonHeight constant in the header file, 
all tlie buttons in the application change to match the new regime. 

Of course, you can extend this for button widths, height 
and widths of other items. 


Extensibility 

Rez is extensible, i.e, you can write resource definitions for 
you own resource types. In fact, Rez comes with a set of header 
files that define the structure of all the common Mac resources 
types; Rez does not have any “built-in” resource types. It does 
have a set of built-in types that you can use as fields in your 
resources, such as bytes, 16 and 32 bit integers, C and Pascal-style 
strings, and a few others. Here’s an example of a C struct definition 
and a corresponding Rez definition: 

// In a header file 

struct FooListEntry ( 
short foolndex: 
short fooValue; 

); 

struct FooResource { 
short fooVersion; 
short fooMinorVersion; 
long fooCount; 

FooListEntry fooList I 1 ] : 

// Really a list of fooCount’ 

1 ; 

typedef struct FooResource FooResource, *FooResourcePtr, 

* *FooResourceHandle; 

type ’Foo!’ I 

integer; //fooVersion 
integer; // minor Version 

long = $$Count0f ( fooList ); // size filled in by Rez 
array fooList ( 
integer; //index 
integer; //value 
); 

); 

// Usage 

resource 'Foo!” ( kDefaultFooList ) ( 

kCurrentFooVersion. kCurrentFooMinorVersion, 
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{ 

12. 23: //Seebug#32 

34. 45; 

45 . 56; // 54 was wrong! changed to 56 mtc 07/02/98 

123, 987; 

); 

); 


In a perfect world, Rez would read C/C++ structure 
definitions directly, and we wouldn’t need to have different 
definitions for the same data structure. However, a Rez definition 
specifies exactly how to lay out the bits in the data structure, 
while C/C++ compilers are allowed considerable leeway in 
structure alignments and padding. Look at Apple’s header files. 
All those lines that start out ‘#pragma options align’ are there to 
control structure alignment so that 68K and PowerPC programs 
can share data structures and data files. 


When Not to Use Rez 

There are some resource types for which Rez is not 
appropriate. For example, there is no real structure for ICON (or 
icl8, etc.) resources. They are really just small bitmaps. So a Rez 
definition of a ICON resource is just a string of hex digits. Icon 
files are better kept as binary files, and edited with a resource 
editor. However, you can still have your cake and eat it too; by 
using Rez to assemble the final resource file. Suppose that you 
have an icon in a file called “Foo.rsrc”, and in that file it is 
‘ICN#’(128). You can include it using Rez thusiy: 

include “Foo.rsrc" *TCN#' ( 128 ) as ‘ICN#’ ( kFoolcon ); 

This will include the icon into your output file, while 
giving it the resource ID that you want (which is defined by a 
symbolic constant). 


Source and configuration control 

There are several source control systems available today. 
Projector, SourceSafe, SCCS, are CVS are just a few. Most of them 
handle binary files, but they all handle text files much better. 
Diffing tools are designed to work on text files. Having your 
resources in text files makes it much easier to track changes, 
additions, and deletions of resources. 

Batch Processing 

Since Rez files are text files, it is easy to generate them from 
other sources. A long time ago, I worked on a project to print 
to plotters. We had a database (in HyperCard!) that contained 
information on a variety of plotters (margins, paper sizes, 
commands supported, etc.). We had many people gather this 
information and enter it into the stack. This stack generated a 
“.r” file that we then compiled. 

Today, a great deal of information is contained in databases. 
Sometimes you have to include information from a database into 
your application. Most databases have extensive report-writing 
facilities. It is usually fairly easy to make a database divulge the 
data that you are interested in formatted in Rez format. This also 
makes it easy to “refresh” the data in your application, by 
including up-to-date information as part of the build process. 
The database could hold anything, from sample data for the user 
to manipulate to the current structure of your web site. 

Translation 

One of the main reasons for the existence of resources is 
to decouple the user interface from the code, thereby making 
changes (especially translation between languages) easier. 
When I wrote printer drivers at HP we put all of our literal 
strings into a single header file, along with comments about 
how the string was used. When the time came for translation, 
we sent this single text file to the people doing the translations. 
They sent us back a translated file, and we built a translated 
driver. After that, all that was required of the translators was to 
adjust the layout of the dialogs, to take into account the 
changed sizes of some of the dialog items. Using this scheme, 
we were able to ship 12 different language versions of our 
driver software within 3 weeks of releasing our English version. 


Conclusion 

Keeping your resources as text files and using a resource 
compiler has many advantages over using a resource file editor. 
You can add comments to your resources, use symbolic 
constants, define your own resource types, and use all the tools 
that exist for maintaining and manipulating text files. The next 
time you find yourself reaching for RcsEdit or Resorcerer, 
consider a third option. Sometimes the old tricks work best, and 
often Rez is the right tool. 
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TELL US ABOUT IT... 
Discover a cool trick that saved you a 
bundle of time? Find a really nasty bug 
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information somewhere so obscure that 
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there? Have an unanswered 
programming question so important that 
you think the world would want to know 
the answer as well? Need some beer 
money? Want your friends to see your 
name in print? Tell us about it! Write it 
up and send it to <tips@mactech.com>. 
We pay $25 for each tip published and 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra , Westford > MA 



Big Baby 

Fifty years ago this past June, the Manchester Mark I 
prototype computer, also known as “Baby”, became operational. 
Baby was the first computer to store a program electronically, 
and was also the first computer to store instructions and data in 
the same memory. Because vacuum tube technology was too 
immature to store memory reliably, Baby was designed to test 
memory based on a cathode ray tube. Not much memory, mind 
you. Baby boasted a full IK bits of memory, organized as 32 
words (or lines) of 32 bits each. 

In celebration of the birth of the first stored program 
computer on June 21,1948, the Department of Computer Science 
at the University of Manchester recently reconstructed Baby and 
ran a programming contest to write the most imaginative 
program for Baby. Inspired by that contest, your Challenge is to 
write an assembler and an emulator for an extended (“Big”) 
version of Baby. The prototype for the code you should write is: 

f if defined(_cplusplus) 

pragma extern "C" { 
ife ndif 

i/define kMaxInstructions 32 

typedef UInt32 CRT_memory[kMaxInstructionsJ: 

pascal void AssembleBabyProgram( 
char ‘program, 

CRT_memory memory, 

UInt32 address_bits 

): 

pascal void ExecuteBabyProgram( 

CRT_memory memory, 

UInt32 address_bits 

): 

#if defined(_cplusplus) 

) 

//end if 

Baby has a single general-purpose register, called the 
Accumulator. The program counter is called the Control 
Instruction, or Cl. The Cl is incremented just before the next 
instruction is fetched, which means that a jump instruction, for 
example, is coded with a value one less than the actual target 
address. Baby also has a red light that indicates the program has 
halted. One interesting thing about Baby is that it lacks an 
addition instruction - addition is done by subtraction. 

Baby’s instruction repertoire is listed below. The function 
bits (or opcode) associated with each instruction is listed in 
parentheses after the mnemonic. 


STO (110) 

SUB (001 or 101) 

LDN (010) 

JMP (000) 


JRP (100) 


CMP (Oil) 


STOP (111) 
NUM (N/A) 


Store the contents of the Accumulator in the 
store line. 

Subtract the contents of the store line from the 
Accumulator. There is no ADD instruction; 
addition is done indirectly by combining the 
SUB and the LDN instruction. 

Copy the contents of the store line, negated, to 
the accumulator. 

Copy the contents of the store line to the Cl 
(so the store line holds the number of the line 
one before we want to jump to). In modern 
terms, this an indirect jump, which uses up an 
extra store line compared to a direct jump. 
Add the contents of the store line to the Cl. 
This looks forward to larger machines, where 
it would be important to be able to load the 
same code in different places, and hence 
would need relative jumps. 

Skip the next instruction if the contents of the 
Accumulator are negative, i.e. a conditional 
branch. 

Stop the machine and turn the red light on 
An assembler mnemonic to initialize a store 
line to a data value. 


For example, the following program computes the greatest 
common divisor of the number in locations 30 and 31: 

22 

0000 NUM 0 
0001 LDN 30 
0002 STO 29 
0003 LDN 31 
0004 STO 31 
0003 LDN 31 
0006 STO 30 
0007 LDN 29 
0008 SUB 30 
0009 CMP 
0010 JRP 27 
0011 SUB 31 
0012 STO 31 
0013 SUB 28 
0014 CMP 
0015 JMP 00 
0016 STP 
0027 NUM -3 
0028 NUM 2 
0029 NUM 0 
0030 NUM 3141593 
0031 NUM 5214 


Baby’s instructions are assembled into a 32 bit word by 
placing the function code associated with the mnemonic into bits 
13-15 (numbered with bit 0 as the most significant bit). In the 
original Baby, the store line associated with the instruction is 
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placed in biLs (M. Bits 5-12 and 16-31 are noi used as part of 
the instruction, although they can be used as data. The program 
listed above assembles to the following: 

22 

0000:00000000000000000000000000000000 
0001:01111000000000100000000000000000 
0002:10111000000001100000000000000000 
0003 : 11 II 1000000000100000000000000000 
0004:11111000000001100000000000000000 
0005:11111000000000100000000000000000 
0006:01111000000001100000000000000000 
0007:10111000000000100000000000000000 
0008:01111000000000010000000000000000 
0009:00000000000000110000000000000000 
0010:11011000000001000000000000000000 
0011:11111000000000010000000000000000 
0012:11111000000001100000000000000000 
0013:00111000000000010000000000000000 
0014:00000000000000110000000000000000 
0015:00000000000000000000000000000000 
0016:00000000000001110000000000000000 
0027:101111111111111111111111 11 I I I 111 
0028:01000000000000000000000000000000 
0029:00000000000000000000000000000000 
0030:10011011111101111111010000000000 
0031 : 01111010001010000000000000000000 


Our contest will make one change to the original Baby: in 
our extended, Big Baby, machine, the store line is extended from 
5 bits (0-4) to address bits bits (0 - address_bits-1). This allows 
more than 32 words of memory and therefore larger programs. 

Your AssembleBabyProgram routine should accept the 
mnemonic input listed above, pointed to by the program 
parameter, and assemble them into 32-bit Baby instructions in 
memory. Your ExecuteBabyProgram routine will be called to 
execute the program one or more times. Both of your routines 
will be provided an address_bits parameter that describes the 
size of memory. You will be asked to assemble more than one 
program, your assembled programs may be executed more than 
one time each, and you may be asked to execute a program that 
has been hand-assembled. 

More information about the University of Manchester Baby 
programming contest can be found at 
<http://www.cs.man.ac.uk/prog98/>. Programming reference 
documentation for Baby can be found at 
<http://www.cs.man.ac.uk/prog98/ssemref.html> and at 
<ftp://ftp.cs.man.ac.uk/pub/CCS-Archive/misc/progref1 .doc>. 

The winner will lx? the solution that assembles and executes 
a set of test programs in the minimum amount of time. 

This will be a native PowerPC Challenge, using the latest 
CodeWarrior environment. Solutions may be coded in C, C++, 
Pascal or, as is our tradition in the month of September, in assembly 
language. Thanks to Eric Shapiro for suggesting this Challenge. 

Three Months Ago Winner 

Congratulations to Tom Saxton for writing the most 
successful simulated gambler at the blackjack table of our June 
Programmer’s Challenge Casino. Tom beat out four other entries 
and was one of only two entries to actually come out ahead at 
the blackjack table. 


Tom precomputed the expected winnings for each situation 
and created tables with the action that led to the besi result. He 
uses the Hi-Lo card counting method to determine whether the 
remaining cards contain a disproportionate number of high¬ 
valued cards, and then uses that estimate to adjust his wager. 
Tom’s solution is also not too greedy; it contains heuristics to 
quit when it has won a reasonable amount or played long 
enough, ensuring that it has wagered enough credits to avoid 
the “freeloader” penalty imposed by the problem. 

A few words about our other gamblers are in order. The 
second-place solution, by Kevin Hewitt, also used precomputed 
tables, but his were based only on the initial pair of cards dealt. 
Kevin also spent more time at the table, quitting only when 
winnings or losses exceeded a threshold. JG Heithcock’s solution 
spent the least amount of time at the table. He quit s<x>n after the 
minimum total bet criterion was met. Ken Slezak kept playing 
until he lost 75% of his bankroll (or quadrupled his money) and 
Randy Boring played until he ran out of money or, as it turned 
out, until the house threw him out of the casino. Both of those 
players left with not much more than the shirts on their backs. 

Here are the statistics for the entries to the Blackjack 
Challenge. Each player played a series of five games where the 
house varied the number of decks of cards used. Players were 
given the same numfxr of credits at the start of each game, totaling 
21000 credits for all of the games. The table below lists the total 
number of credits wagered by the player, the number of credits left 
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when the player decided to quit, the number of hands played, total 
execution time, and the overall player score. Also listed are the 
code and data sizes for the entries, along with the programming 
language used. As usual, the number in parentheses after the 
entrant’s name is the total number of Challenge points earned in 
all Challenges to date prior to this one. 


Name 

Credits 

Credits 

Hands 

Exec. 

Score 

Code 

Data 

Lang 

Wagered 

Left 

Played 

Time 


Size 

Size 


Tom Saxton (19) 

47451 

25199 

327 

7169 

25194 

1496 

1924 

C 

Kevin Hewitt 

438700 

23800 

1833 

37923 

23766 

996 

2156 

C 

JG lleilhcock (20) 

22616 

20484 

769 

17950 

20470 

1304 

232 

C 

Ken Slezak (20) 

91760 

9140 

1701 

36911 

9106 

1240 

172 

C 

Randy Boring (81) 137230 

8670 

15425 

460099 

8213 

4920 

353 

C 


Top Contestants 

Here are the Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated more than 
20 points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month’s entrants. 


Rank 

Name 

Points 

Rank 

Name 

Points 

1. 

Munter, Ernst 

190 

10. 

Heithcock, JG 

27 

2. 

Boring, Randy 

76 

11. 

Gregs, Xan 

24 

3. 

Cooper, Greg 

54 

12. 

Murphy, ACC 

24 

4 

Mallett, Jeff 

50 

13. 

Hart, Alan 

21 

5. 

Rieken, Willeke 

47 

14. 

Antoniewicz, Andy 

20 

6. 

Nicolle, Ludovic 

34 

15. 

Day, Mark 

20 

7. 

Lewis, Peter 

31 

16. 

Higgins, Charles 

20 

8. 

Maurer, Sebastian 

30 

17. 

Hostetter, Mat 

20 

9. 

Saxton, Tom 

29 

IS 

Sluder, Thomas 

20 


There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are: 


1st place. 

2nd place. 

3rd place. 

4th place. 

5th place. 

Finding bug. 

Suggesting Challenge. 


.20 points 
.10 points 
.7 points 
.4 points 
.2 points 
.2 points 
2 points 


Here is Tom’s winning solution: 

Player.c 

Copyright © 1998 Torn Saxton 

//include “Blackjack.h" 

// Naming Conventions: 

// 

//Without getting into the gory details of the Hungarian naming convention, 


// here are some common prefixes and their meanings: 
ff 

// a array 

// p pointer 

// c count 

// mp map (one data type to another) 

// i index 

// 

//The prefixes modify a base type. So, if FOO is a base type (like a struct, 

// or an enum), the following declarations illustrate the above prefixes: 

ft 

ft FOO fbo; 

// FOO * pfbo; 

// FOO afoo[ 10]; 

// int ifoo; If an index into an array of FOOs 

// int cfoo; // a count of F(X)s. 

// 

// for (ifoo = 0; ifoo < cfoo; ++ifno) 

// pfoo = &afoo[itbo]; 

// 

enum t fFalse = 0, fTrue = 1 ); 

//define DIM(a) (sizeof (a)/sizeof ((a) [0l)) 

// Be sure to enable this define to pick up a couple of post-deadline bug fixes. 

ff 

// ^define BUGFIX 

// disable debug code 
^define Assert(f) 

//The following tables determine the actions tor all possible hands, 

// divided into three groups: pairs, soft hands and hard hands, considered 
// in that order. (A pair of aces is treated as a pair, not as a soft hand.) 

ft 

//The tables were computed by taking the Dealer’s up card and assuming 
// a huge shoe with an even card distribution finding the probability 
// for each of the possible final dealers scores (bust, 17,18.19,20 and 21). 

If 

ff Then, given that table, 1 computed the expected earnings (win, lose or 
// push) for each of the possible actions, and recorded the action with 
// the best result. 

If 

ff I found the book "Best Blackjack” by Frank Scobletc (c) 1996 to be 
// helpful, and my tables are close to his multi-deck tables. 

// 1 modeled an infinite, evenly distributed shoe, he may have modeled 
// a fixed number of decks. 

// macros to make these tables manageable... 

//define H kHitMe 
//define D kDoubleDownAndHi tMe 
//define S kStandPat 
//define X kSplitAndHilMo 
//define B kClaimBlackjack 

// For “hard” hands (no Aces scored as 11), plug in the dealer’s up card 
// (minus I) and the hand’s score to find the next action. If this isn’t the 
// first action of the hand, treat kDoubleDownAndHitMe as kHitMe. 

Action mp_spot_score_actionHardf10][22] - 

( 

ft 0-21 

f H,H,H,H,H,H,H,H,H,H,H,H,II,1I,U,11,H,S,S,S,S,S 1 
I H,H,H,H,H,H,H,H,H,D,D,D,H,S,S,S,S,S,S,S,S,S 1 
{ H,H,H,H,H,H,H,H,H,D,D,D,H,S,S,S,S,S,S,S,S,S ) 

( H,H,H,H,H,H,ii,H,H,D,D,D,S,S,S,S,S,S,S,S,S,S ) 

( H,H,H,H,H,il,ll,H,H,D,D,D,S,S,S,S,S,S,S,S,S,S } 

( h,h,h,h,h,h,h,h,d,d,d,d,s,s,s,s,s,s,s,s,s,s ) 

( 1I,11,H,H,H,H,H,H,H,D,D,D,H,H,H,H,H,S,S,S,S,S 1 
I H,H,H,H,H,H,H,H,H,H,D,D,H,H,H,H,H,S,S,S,S,S 1 
I ,S,S,S } 

( H,H,H,H,H,H,H,H,H,H,H,D,11,H,H,H,H,S,S,S,S,S 1 

); 


r A 7 
r 2 7 
T 37 

r 47 
r 57 
r 67 
r 77 
r 8 7 
r 97 
r 107 


// For “soft” hands (at least one Ace used as an 11), plug in the dealer’s up card 
// (minus 1) and the hand’s “other" card (or combined score without the acc) 
// to find the next action. 

Action mp_spot_spot_actionSoft[10] [10] = 

( 


H, H, H, H, H, H, 

S, S, S, B 1 

. r A7 

H, H, H, H, H, D, 

S, S, S, B I 

. r 27 

H, H, H, H, H, D, 

0, S, S, B 1 

. r 3 7 

H, H, H, H, D, D, 

D, S, S, B ) 

, r 47 


50 
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( H, H, H, D, 
l H, H, H, D, 
( H, H, H, H, 
( H, H, H, H, 
1 H, H, H, H, 
( H, H, H, H, 


D, D, D, S, 
D, D, D, S, 
H, D, S, S, 
H, H, S, S, 
H, H, H, S, 
H, H, H, S, 


S, B 

}. r 57 

S, B 

j . r 6 7 

S, B 

). r 77 

S, B 

i. r 87 

S, B 

). r 97 

S, B 

) r io 7 


// If dealt a pair, plug in the dealer’s up card (minus 1) and the spot 
// value of the pair (minus 1) to find the suggested action. 

Action mp_spot_spot_actionPair[10][10] = 

I 


( X, 
( X, 

( x, 
( X, 
( X, 
{ X, 
( X, 
1 X, 
( X, 
( X, 


H, H, H, H, H, H, H, 

X, X, H, D, H, X, X, 

X, X, H, D, H, X, X, 

X, X, H, D, X, X, X, 

X, X, 11, D, X, X, X, 

X, X, D, D, X, X, X, 

X, X, H, D, H, X, X, 

X, X, H, D, H, H, X, 

X, H, H, D, H, H, X, 

H, H, H, H, H, H, H, 


S, S 1 
X, S 1 
X, S ) 
X, S ) 
X, S ) 
X, S ) 
S, S ) 
X, S ) 
X, S ) 
S, S ) 


r a v 
r 2*i 
r 37 

r 4 7 
r 57 
r 67 
r 77 
r 87 
r 97 
r 107 


// undefine shortcuts used in the above tables 

//undef H 

//undef D 

ifundef S 

//undof X 

ifundef B 

// Score bust as zero. 

//define scoreBust 0 

//The Players hand is limited to five cards, 

//define ccardMaxPlayer b 

//The dealer can never draw more than nine cards 
// (nine 2’s tor example). 

//define ccardMaxDealer 10 


// Entry in the SPOT table, used tor scoring and printing card values 

typedef struct ESPOT 

{ 

char score; 
char sz [3] ; 

J ESPOT; 

static const ESPOT s dnspot[kKing+1] = 

I 

( 0, T ). 

( 1. “A” ). 

( 2, “2” ), 

1 3. "3" 1, 

1 4 . - 4 " 1 , 

( 5, “5” }, 

I 6. “6" I. 

( /. **7- ). 

I 8. “8” }. 

I 9. “9" ). 

{ 10 . “ 10 ” ). 

I 10. “J” ), 
l 10. “Q" ). 

I 10. “K M ). 

); 


// game statistics... 
static int s_cdeck; 
static int s_ccreditStart; 
static int s_ccreditMinBet; 
static int s_ccreditMidBet: 
static int s ccreditMaxBet; 
static int s ccreditBalance; 
static int s_ccreditTotalBet; 


// callback functions 

static BetProc *s_pfnMakeABet; 
static HitProc *s_pfnHitMe; 

// function to score a hand 

static int ScoreHand(const Card acard[], int ccard. 
int *pcAce); 


// struct for counting cards... 


typedef struct DECK 

( 

int aespot[10+1]; 
int cspotStart; 
int cspotRemain; 
int dcount; 
int. fInfinite; 

} DECK; 

static DECK s_deck; 

// calls to reset card counters and count the cards in a hand 
void _lnitDeck(int cdeck, int fInfinite); 
void _CountCards(const Card acard[], int ccard); 

// call to compute the proper action given the player's hand and 

// the dealer’s up card, and whether or not this is the first action 

static Action _ActionLookupHand(Spot spolDcaler, Card acard[], 

int ccard, int fFirst); 


InitBlackjack 

// Call to start a game 
void InitBlackjack( 

int numDecks. /* number of decks used by the dealer, 2.. 107 

int yourBankroll. /* number of credits you have to start 7 
int minBet. /* minimum bet for each hand 7 

i nt maxBet, /* maximum bet for each hand 7 

Bot Proc pfnMakeABet. /* callback to place a wager 7 
HitProc pfnHitMe /* callback to get a card 7 


s_cdeck 

s_ccreditStart 
s ccreditMinBet 
s ccreditMaxBet 
s_pfnMakeABet 
s_pfnHitMe 


* numDecks; 

= yourBankroll; 
= minBet; 

= maxBet; 

“ pfnMakeABet; 

= pfnHitMe: 


s_ccreditTotalBet • 0; 
s_ccreditBalance= s_ccreditStart; 


"IN JUST A FEW SECONDS I'VE SUCCESSFULLY TRACKED 
ING ME FOR ABOUT 3 MONTHS. FANTASTIC »" 

-Bryan Christianson- 
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Blackjack 

// Call to play a hand 

Boolean Blackjack(Boolean fNewDeck) 

l 

int ccreditBet; 

Card acardPlayer[ccardMaxPlayer], acardDealer[ccardMaxDealer]; 
ini ccardPlayer, ccardDealer; 

Action actionFirst; 
int ccreditWin; 

Spot spotDealer; 
int ihand, chand; 
int count: 

Result result; 

if (fNewDeck) 

_InitDeck(s_cdeck, fFalse /‘flnfinitc*/) ; 

// normalize the card count. A positive count means that the shoe is 
// heavy in large cards, which makes it more likely for the dealer to 
// bust. A negative count means that the shoe is heavy in small cards, 

// which makes it less likely that the dealer with hast, 
count = (s_deck.dcount*52)/s deck.cspolRemain: 

// Make a bet that is proportional to our current balance, so that losing 
// streaks don’t clean us out, and winning streaks rake in extra chips. 

// Bet more when the count is high, less when it’s low, but stay within 
// the stated betting limits. 

ccreditBet “ (count+2)*s_ccreditBalance/50: 
if (ccreditBet < s_ccreditMinBet) 
ccreditBet * s_ccreditMinBet; 
else if (ccreditBet > s_ccreditMaxBet) 
ccreditBet - s_ccreditMaxBet.; 

// Place bet, get some cards 

(*s_pfnMakeABet)(ccreditBet, acardPlayer, acardDealer); 
ccardPlayer * ccardDealer = 2; 

// store and normalize the dealer’s up card 
spotDealer = acardDealer[1].spot; 
if (spotDealer > klO) 
spotDealer - klO; 

// get the first action for the hand 
actionFirst = 

_ActionLookupHand(spotDealer. acardPlayer, 2, fTrue): 
if (actionFirst = kDoubleDownAndHitMe) 
ccreditBet *= 2; 

chand - (actionFirst == kSpiitAndHitMe) ? 2 : 1; 

// play out the hand(s) (there arc two hands if we kSpiitAndHitMe) 

for (ihand ~ 0; ihand < chand; ++ihand) 

1 

Boolean fInsurance; 

Action action = actionFirst; 

// lake the “insurance" side bet when the dealer shows an Ace and there is 
// a better than one third chance of the dealer having a 10 for the other card. 

flnsurance * (spotDealer — kAce) && 

(3*s_deck.acspot[klO] > s_deck.cspotRemain): 

for(;;) 

I 

// play out an action 

result - 

(*s_pfnHitMe)(act Ion, flnsurance, acardPlayer. 

^ccardPlayer. acardDealer. ^ccardDealer. 
&ccreditWin); 
if (result !■ kNoResult) 
break: 

// If wc didn’t kStandPat or bust, calculate the next action 

action = _ 

AetionLookupHand(spotDealer. acardPlayer, ccardPlayer. 


// count the cards shown in this hand 

CountCards(acardPlayer, ccardPlayer); 
if (ihand = chand-1) 

_CountCards(acardDealer. ccardDealer); 

// tally our win/loss 

s_ccreditBalance ccreditWin; 

s_ccreditTotalBcl += ccreditBet; 

} 

// If we have lost most of our money, quit 

if (s_ccreditBalance < s ccredilStart/3) 

I 

return fFalse; 

1 

// If we have won a lot, and will avoid the freeloader penalty, quit 


if (s_cereditBalance > 7*s_ccreditStart/4 && 
s_ccreditTotalBet > s_ccreditStart) 

{ 

return fFalse; 

I 

// If we have won some, and played for twice the freeloader requirement, quit 

if (s ccreditBalance > 5*s_ccreditStart/4 && 
s_ccreditTotalBet > 2*s ccreditStart) 

( 

return fFalse; 

1 

// If wc haven’t lost, and played for five times the frtekrader requirement, quit 

if (s_ccreditBalance > s_ccreditStart && 

s ccreditTotalBet > 5*s_ccreditStart) 

( 

return fFalse; 

1 

// If we’ve played 10 times the freeloader penalty, quit before the time penalty 
// takes it all away... 

if (s_ccreditTotalBet > 10*s_ccreditStart) 

I 

return fFalse; 

1 

return fTrue; 


AetionLookupHand 

// Call to get the next action for this hand 

static Action Actionl.ookuplland(Spot spotDealer, Card acard[], 
int ccard, int fFirst) 

1 

int score, cAce; 

Spot spot; 

Action action; 

// get the hand's score, and the count of Aces scored as 11 

score - _ScoreHand(acard, ccard, &cAce); 

Assert(kAce <= spotDealer && spotDealer <= klO); 
if (fFirst && ccard = 2 && acard[01.spot — acard[1].spot) 

( 

// first action on a pair, check the pair’s table 
if ((spot = acardfOl.spot) > klO) 
spot = klO; 
action = 

(Action)mp spot spot_actionPairIspotDealer-1][spot 1] ; 

1 

else if (cAce > 0) 

I 

// “soft” hand, check the soft table 

spot = (Spot)(score - 11); 

Assert(kAce <“ spot && spot <= klO); 
tfifdef DEBUG 

if (ccard = 2) 

1 

int icard ■ acard [Oj .spot — kAce ? 1 : 0; 

Assert(spot = acard[icardl.spot | 

(spot — klO hb acard[icardj.spot > klO)); 

1 

//end if 

action — 

(Action)mp spot spol_actionSoft[spotDealer-1)[spot-1]; 

) 

else 

I 

// “hard” hand, chcch the hard table 

action = 

(Action)mp_spot score actionHard(spotDealer-1][score]; 

I 

// If it’s not the first play of the hand, wc can only kStandPat or kHitMe 

#lfdef BUGFIX 

//Another Bug Fix: he careful trying to catch illegal actions... 

if (action — kClairaBlackjack && ccard != 2) 
action = kStandPat: 

if (!fFirst && (action = kDoubleDownAndHitMe | 

action “ kSpiitAndHitMe)) 

action - kHitMe; 

//else 

//This code is wrong, it incorrectly returns kllitMc in two cases: 

// 1. If a pair of 10s or Aces is split, then one of them turned into a bLickjack 
// 2. A score of 21 is reached with an Ace and two or more cards. 

if (!fFirst && action != kStandPat) 
action = kHitMe: 


52 


Programmer’s Challenge 


MacTech • September 1998 












#endif 

return action: 
I 


JnitDcck 

// reset the counts for a fresh set of decks 

static void _Initl)eck(int cdeck. int flnfinite) 

{ 

Spot spot: 

int cspot * 4*cdeck: 
for (spot “ kAce: spot < klO; ++spot) 
s deck.acspot [spot.] = c.spot; 

Assert, (spot = k 10): 
s_deck.acspot[k10] ~ 4*cspoL; 

s_deck.cspotRemain = s_deck.cspotStart - 52*cdeck: 

s_deck.dcount = 0; 

s_deck.flnfinite = flnfinite: 


_CountCards 

//This is the counting method used by the couple of people I’ve talked 
// who have actually counted cards playing Blackjack: It’s call “Hi-Lo" 

// in “Best Blackjack". I tried several other counting models listed 
// in that book, and this performed the best. It gives a simple assessment 
// of how far off balance the shoe is with respect to small and large cards, 
static const int s_mp_spot_dcount[klO+ll = 

// A 2 3 4 5 6 7 8 9 10 
{ 0. -1, 1. 1. 1. 1. 1. 0. 0, 0. -I I; 

// Remove the specified set of cards from the shoe 

void _CountCards(const Card acard[], int ccard) 

( 

if (s_deck.flnfinite) 
return: 

while (ccard- > 0) 

{ 

Spot spot. = acard[ccard].spot; 

// Bug Fix: we shouldn't count hidden cards... 

//ifdef BUGFIX 

if (spot = klliddenSpot) 
continue; 

#endif 

if (spot > klO) 
spot * klO: 

-s deck.acspot.[spot] ; 

-s deck.cspotRemain; 

s_deck.dcount +* s_mp_spot_dcountIspot] ; 

I 

1 


jScoreHand 

// Determine the score for the given cards.When possible, score 
//Aces at 11, and return the number of aces thusly scored. 

static int _ScorcHand(const Card acard[]. int ccard. int *pcAce) 

( 

int cAceDummy: 
int score = 0; 
int cAce * 0: 

if (pcAce — NULL) 
pcAce = &c.AceDummy; 

*pcAce * 0; 

while (ccard > 0) 

t 

if (acard[ccard].spot = kAce) 

++cAce; 

score +- s_dnspot[acard[ccardl.spot].score: 

) 

if (score > 21) 
return scorcBust; 

while (score + 10 <= 21 && cAce > 0) 
l 

score += 10; 

-cAce; 

++*pcAce; 

1 

return score; 

) 

m 
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FROM THE 

FACTORY 

FLOOR 


by Howard Hinnant and Dave Mark. ©1998 by Metrowerks, Inc., all rights reserved. 


The New C++ Standard: 

Partial Template Specialization 


In last month’s column, we continued 
our exploration of the new C++ standard, 
specifically taking a look at the subject of 
locales. In this month’s column, Howard 
Hinnant is back once again, and will lake 
us through partial template specialization. 


Howard Hinnant is a software 
engineer on the MSI team at Metrowerks, 
and is responsible for the C++ and EC++ 
libraries. Howard is a refugee from the 
aerospace industiy where FORTRAN still 
rules. He has extensive experience in 
scientific computing including C++ 
implementations of linear algebra, finite 
difference and finite element solvers. 

Dave: What exactly is partial 

template specialization? 

Howard: In order to explain partial 
template specialization, it might first be 
easier to describe full template 
specialization. Consider: 

template <class T> 
class vector 
I 


This works well for most items that we 
might want to keep a list of. However, if 
we wanted to keep a vector<bool>, then 
an obvious optimization would be store 
each value in one bit, instead of actually 
storing a list of bools. This could be 
neatly accomplished by defining a 
specialization of our vector class: 

template <> 
class vector<bool> 

( 


This is known as template specialization. 

Now consider a class template with two type parameters. I ll 
keep picking on vector: 

template <class T, class Allocator) 
class vector ( 

i;* 

And let’s say we still want to optimize for when T == bool. 
We can do this by: 

template <class Allocator) 
class vector<bool, Allocator) ( 

i;’ 

Since not all template parameters have been nailed down, 
this is known as partial template specialization. So now when 
I say: 

vector<bool. myAllocator) a: 

I get the optimized implementation for bool. 

Dave: Cool. Any other useful optimizations you could do? 

Howard: You can do some really cool things with this concept. 
For example, let’s say you wanted to make a special vector 
for holding pointers. Here is a possibility: 

template <class T, class Allocator) 
class vector<T*. Allocator) 

[ 

)Y 

This might come in handy if you wanted some special 
behavior for when the element type was a pointer to 
something. For instance, one might want to treat vectors of 
pointers as pointing to heap based objects, and manage those 
pointers with new and delete. The standard library, of course, 
docs not do this. 

Dave: So how does partial template specialization affect 
the standard library? 
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Howard: MSL does use partial template specialization to 
implement vector<bool> as alluded to earlier. Additionally, 
there is a struct in <iterator> that looks like: 

template <class Iterator) 
struct iterator_traits 
( 

typcdcf typename Iterator::difference_type 
difference_type: 

typedef typename Iterator::value type value_type; 
typedef typename Iterator::pointer pointer; 
typedef typename Iterator::reference reference; 
typedef typename Iterator;:iterator_category 


The purpose of this class is to help code that takes iterators find 
out valuable things about the iterator that it’s working on. For 
example, consider the standard algorithm iter_swap that takes 
two iterators, and swaps the values that the iterators point to: 

template <class ForwardlteratorI, class ForwardIterator2> 
void 

iter swap(ForwardIlcratorl a. ForwardIterator2 b) 

I 

typedef typename 

iterator_traits<ForwardIteratorl>::value_type Value; 

Value tmp(*a); 

*a = *b: 

*b • tmp: 

} 

The routine iter_swap must create a temporary variable in 
order to accomplish the swap. But what is the type of the 
temporary? Ii queries the iterator to find out the proper type. 

Thus all valid iterators (at least those that want to be used in 
standard algorithms and containers) must create the typedefs 
referred to above so that they can be queried via 
iterator_traits. This can be easily accomplished by deriving 
your custom iterators from the standard iterator struct: 

In <iterator>: 

template <class Category, class T, class Distance * 
ptrdiffjt, 

class Pointer = T*, class Reference ~ T&> 
struct iterator 
{ 

typedef Distance difference_type; 

typedef T value_type; 

typedef Pointer pointer; 

typedef Reference reference; 
typedef Category iterator category; 

); 


In your code: 
class Mylterator 

: public std::iterator<random_access_iterator_tag, 

MyClass) 

{ 

i; * 

Dave: I see. But if I remember right, an iterator is just a 
generalization of a built-in pointer. In fact, built-in 
pointers can be used in all the standard algorithms. So 
how does iter_swap query a built-in pointer for its 
value_type? You can’t derive hit* from std::iterator. 


Howard: Ahh... Exactly! This is where partial template 
specialization rides in to save the day. The standard library 
defines a specialization of iterator jraits for a pointer to anything: 

template <class T> 
struct iterator_traits<T*> 

{ 

typcdcf ptrdiff_t difference_type; 
typedef T value_type; 

typedef T* pointer; 

typedef T& reference; 

typedef random access iterator_tagilcralor_category; 

); 

So now when itcr_swap tries to define Value: 

typedef typename 

iterator_traits<Forwardlteratorl>::vaiue_type Value; 

And Forwardlteratorl has the type ini*, iicrator_traits<int*> 
picks up the partial specialization and answers back with int. 
This is really a pretty slick design. 

Dave: That is neat. But partial template specialization is 
a relatively new feature of CodeWarrior. How did MSL 
handle this problem before this feature was available? 

Howard: Oh, yes... The Dark Time. We took advantage of the 
fact that we did have full template specialization available to 
us. So we created full specializations for iterator Jraits for 
every type we could think of: char*, int*, bool*, short*, long* 
... plus all combinations of unsigned and const modifiers. 
This worked pretty well except for one minor little detail. We 
could not creaLc a specialization for myType*. Here myType 
represents all of the classes which the customer created. 

In order to combat this last problem, we (actually Dennis C. 
De Mars) created a macro which defined a full specialization 
of iterator jraits for its argument myType: 

//define _MSL_FIXJTERATORS_(myType) \ 

templateO \ 

struct std::iterator traits <myType*> ( \ 

typedef ptrdiff_t difference^ype; \ 

typedef myType valuc_type; \ 

typedef myType* pointer; \ 

typedef myTypc& reference; \ 

typedef randoin_accessJterator_tag iterator_category: \ 

1 ; 

Yes, everyone knows about _MSL_FIX_ITERATORS_. And 

you now know the full story behind this macro. It is a macro 
that no one liked, but we could not live without it. 

Even if you didn’t use the standard algorithms, you got bit by 
this when you used the standard containers, because they 
used it. We had plans to reduce MSL’s dependence on 
iterator Jraits, but Andreas (our C++ compiler guru) came out 
with partial specialization before we could implement those 
plans. This was really best as we could have only reduced 
the dependence, not eliminated it. 

ES3 
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JAVATECH 


by Andrew Downs 

Edited by lbe MacTech Editorial Staff 


Growing Java Beans 


A code-based intro to 
Java’s component 


• generate or respond to appropriate events; 

• save their state using the Java Serialization mechanism. 


architecture 


Introduction 

JavaBeans is the Java component 
architecture. This article discusses and 
demonstrates how to write several simple 
components (hereafter referred to as 
Beans). The reader should have a general 
familiarity with Java. The code in this 
article was developed using the Apple 
Mac OS Runtime for Java (MRJ) version 2.0 
and the MRJ SDK 2.0.1 ea2. 

For additional background information, 
several related articles previously published 
in Mac lech are listed in the reference section 
at the end of this article. Several lxx)k$ are 
also listed. 


In this article, we will explore the code behind two relatively 
simple Beans. They contain enough of the alx>ve-listed features 
to make them interesting, while remaining easy to read and 
understand. One of the Beans displays a sequence of lights similar 
to a U.S.-style traffic light. The other Bean changes the sequence 
of the light display. We will look at the code for these classes later. 

Figure 1 shows the two Beans running within a Java 
Frame object. (A Frame is a platform-specific window.) Figure 
2 shows the Beans running inside the BeanBox, a GUI tool 
from JavaSoftthat allows you to instantiate, connect, and test 
Bean behavior. The BeanBox is provided free of charge from 
JavaSoft, as part of the Beans Development Kit (BDK). Since it 
is written in Java, the BeanBox can be installed on the 
Macintosh using the MRJ Software Development Kit tools. Ii can 
then be run the same as other Java applications. The URL for 
obtaining the BeanBox is provided at the end of this article. 
(Note: you will need a file-extraction program that can open 
.zip files in order to unpack the BeanBox.) 


Overview 

A Java Bean bears a strong resemblance 
to a well-written Java application. But since 
it is a component, a Bean’s scope is usually 
smaller than that of an entire application, 
making it easier to develop. 

Flere is a partial list of Bean 
characteristics. Beans should: 

• expose accessor methods (e.g. 
getValueQ and setValueQ) to allow 
retrieval and changing of attribute 
values by external sources; 

• allow for easy mixing and matching via 
GUI development tools; 



Figure 1 . The finished product running in its own 
container (a Frame). 


Andrew Downs is a Senior Software Engineer for Template Software in New Orleans, LA, designing and building enterprise 
apps. He’s trying to teach his twin sons that mice are for pointing, not eating. Andrew wrote the Macintosh freeware program 
Recent Additions, and the Java application UDPing. You can reach him at andrew@nola.template.com. 
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Figure 2. Running inside the BeanBox. 


Choice Bean 

The ModeSelector Bean is a Choice menu component (a 
popup menu on the Mac). When the user changes the currently 
selected item, the Bean notifies any registered listeners. (We will 
see that the DisplayFrame class instantiates a Display object and 
registers it as a listener on a ModeSelector object.) 


Listing 2: ModeSelector.)ava 


ModeSelector. java 

//A Choice menu class lor changing the display mode (and resulting light sequence). 

// Make available the following packages and classes: 

import, java.awt.*; 
import java.awt.event.*; 
import java.beans.*; 
import java.io.Serializable: 
import java.util.Vector: 


Notice that there is little difference in the visible display of 
the Beans, whether running standalone or in the BeanBox. One 
Bean appears as a Java Choice menu (a Mac OS popup menu), 
and the other is a rectangle containing three circles, one of 
which is filled at any given time. 

There are four classes that comprise this project: 


ModeSelector specifies that it implements the ItemListener 
interface so that it can receive item changed events (generated 
when the user makes a selection). The method that must be 
defined for the ItemListener interface is itemStateChangedO. In 
this implementation, ModeSelector ignores the event object 
contents, and checks its own state instead. 


• Global: values shared by the other classes. 

• ModeSelector: a Choice (popup) menu, which specifies the 
mode of operation: in “normal” mode the lights flash in 
sequence (green - yellow - red), and in “maintenance” mode 
only the yellow light flashes. 

• Display: the component which draws the lights. Display also 
runs a Thread which adds timing capability to its operation. 

• DisplayFrame: a container for the Display and 
ModeSelector Beans. 

We will cover each of these classes in sequence. 

Global Values 

This class defines some global values that are shared between 
the Display and ModeSelector classes. These values are collected 
in one place to simplify housekeeping and maintenance. We will 
refer to them from the other classes as Global.NORMAL, 
Global.sleep, etc. This is the java syntax for referencing static 
(class) attributes. Note that final means Lhe values cannot be 
changed after they are initially assigned, so these are constants. 

Listing 1: Global.java 

Global.java 

// Shared values, 
public class Global { 

// Mode values; all-caps to set them off from Strings of same name. 

public static final int NORMAL = 0. MAINT = 1; 

// Number of milliseconds for Thread to sleep. 

public static final int sleep = 250; 

// Choice menu item values. 

public static final String normal = “Normal”; 
public static final String maint = “Maintenance”; 


public class ModeScleclor extends Choice implements 
ItemListener, Serializable ( 

// Mode value. 

private int mode - Global.NORMAL; 
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// Keep track of other objects that want to be informed of changes, 
private PropertyChangeSupport changeListeners = 
new PropertyChangeSupport( this ); 

public ModeSelector() { 

// Call the superclass constructor. 

super(); 

// Only two items in this menu, 
this.add( Global.normal ); 
this.add( Global.maint ); 

// Starting mode. 

this.setMode( Global .NORMAL ); 

// Listen for selections on ourself. 

this.addltemListener( ( ItemListener )this ); 

) 


ModeSelector uses its own accessor methods to get and set 
the mode value. This may seem like overkill, since a class can 
access its own variables (even private ones, such as mode) 
directly. However, it is arguably a good habit, since variable 
references from outside the class should go through accessor 
methods, and never directly access variable values. 

public int getModeO { 

// Simple accessor function. 

return this.mode; 

) 

public void setMode( int i ) I 

// More complex accessor function. 

// Store the current mode. 

int old = this.getModeO ; 

// Set the current mode. 

if ( i = Global.NORMAL ) 
this.mode = Global.NORMAL; 
else 

this.mode = Global.MAINT; 

// Notify^ our customers of the change. 

this.changeListeners.firePropertyChange( “mode", 

new lnteger( old ), new Integer! this.getModeO ) ); 

1 

public void itemStateChanged( ItemEvent evt ) { 

// If the selected item has actually changed, then change the mode accordingly, 
if ( ( this.getSelectedlndex() = Global.NORMAL ) 

&& ( this.getModeO = Global.MAINT ) ) 
this.setMode( Global.NORMAL ); 
else if ( ( this.getSelectedlndex!) = Global.MAINT ) 

&& ( this.getModeO = Global.NORMAL ) ) 
this.setMode! Global.MAINT ); 

} 

public void addPropertyChange.List.ener! 

PropertyChangeListener 1 ) { 

// Add someone else as a customer. 

changeListeners.addPropertyChangeListener( 1 ); 

1 

public void removePropertyChangeListener( 
PropertyChangeListener 1 ) ( 

// Remove a customer. 

changeListeners.removePropertyChangeListener( 1 ); 

} 

1 

Note that ModeSelector does not define any unique 
serialization that needs to occur. Instead, it uses the 
superclass’ implementation. 


Center of Attention 

This Bean defines the lights that will be drawn as part of 
the traffic light, it also contains a Thread which is used to 
time the repaints. 

Note that Display inherits directly from 
java.awt.Component. This makes it a “lightweight” component 
(as well as a Bean), which simply means that it has no native 
window object associated with it at runtime, and also none of 
the overhead associated with such an object. 

Listing 3: Display.java 


Display.java 

//The traffic light class, which sequences and draws the colored lights. 

import java.awt.*; 
import java.awt.event.*; 
import java.beans. *; 
import java.io.*; 
import java.util.*; 

public class Display extends Component implements 

PropertyChangeListener, ItemListener, Serializable, 

Runnable { 

// Size matters. 

private int width = 50, height = 165; 

// count = number of seconds. 

// mode determines display pattern. 

// interval = number of milliseconds for Thread to sleep. 

private int count = 0, mode = Global.MAINT, interval = 
Global.sleep; 

// color becomes important in NORMAL mode, 
private Color color; 

//Thread is not Serializable. 

transient private Thread runner; 

public Display!) ( 

// Gill the superclass constructor, 
super!); 

//We know how big we want to be. 

this.setSize! this.getPreferredSize() ); 

// Set some instance variables. 

this.setMode( Global.NORMAL ); 

this.setColor! Color.red ); 

// Create and start a Thread. 

runner = new Thread! this ); 
runner.start(); 

) 

The runner object used in this class, in conjunction with the 
Runnable interface, allows Display to take on the behavior of a 
'thread without actually subclassing directly from Thread. In the 
run() method, the runner is put to sleep temporarily. On wakeup, 
it compares the current time to the reference time, and if the 
reference time has been exceeded, this object’s state gets 
updated (i.e. the light color may change). 

public void run() ( 

// Reference point will be current lime plus 1 second. 

Calendar triggerTime = Calendar.getlnstance(); 
triggerTime.add( Calendar.SECOND, 1 ); 

while ( true ) { 
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try I 

// Sleep for <interval> milliseconds. 

Thread.sleep! this.interval ); 

) 

catch ( InterruptedExeeption ex ) ( 

System.out.println( "InterruptedExeeption..." ); 


// Compare the current time to the reference point. 

if ( Calendar.getTnstanceO.after( triggerTime ) ) I 
//Take action, 
this.timerExpired(): 

// Reset the reference point. 

triggerTime = Calendar.getlnstance(); 
t-riggerTime.add( Calendar .SECOND. 1 ); 

) 

} 

I 


Overriding the getPreferredSize() method (whose original 
definition is in java.awt.Component) enables us to specify the 
desired size (in pixels) of this object. Notice that the preferred 
size will also lx? the minimum size. If we do not override these 
methods, some containers (such as the BeanBox) will not 
automatically size the object so that the lights are visible. 

public Dimension getPreferredSizeO I 

//When queried, we know how big we ’want’ to be. 

return new Dimension! this.width, this.height ); 


public Dimension getMiniaumSize() ( 

// Our preferred size is already the minimum size, 
return this.getPreferredSize(); 


The itemStateChanged() method allows this component to be 
dynamically connected to a source of ItemKvents, such as the 
ModeSelector class. Without it, you must directly bind the 
“mode” property of both classes in order to see a state change 
while running in the BeanBox. 

public void itemStateChanged( ItemEvent evt ) I 

// If the selected item has actually changed, 

// then change the mode accordingly. 

//This is the same method as in ModeSelector.java. 

// Here, it allows this Component to receive changes directly, 

// and get hooked up in the BeanBox. 

if ( evt .getltemO .toStringO .equals! Global .normal ) 

&& this.getMode!) = Global.MAINT ) ( 
this.setMode! Global.NORMAL ); 
this.reset!); 

} 

else if 

( evt.getltem!).toString!).equals! Global.mainL ) 

&& this.getMode!) = Global.NORMAL ) ( 
this.setMode! Global.MAINT ); 
this.reset(); 

I 

) 

The following method gets called from run() approximately 
every second. The timing used here is simple: in normal mode, 
each light will be “on” for five seconds; in maintenance mode, 
that interval is reduced to one second. 

In terms of color, normal mode sequences the lights (green, 
then yellow, then red), while maintenance mode only flashes the 
yellow light. 
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public void timerExpiredO 1 

// count is the number of elapsed seconds. 

this.count++; 

if ( this. getModeO = Global.NORMAL ) ( 

// In normal mode, each light stays on for 5 seconds, 
if ( this.count > 4 ) { 
this.count - 0: 

// Cycle through the light sequence. 

if ( this.getColor() = Color.red ) 
this.setColor( Color.green ); 
else if ( this.getColor() = Color.yellow ) 
this.setColor( Color.red ); 
else 

this.setColor( Color.yellow ); 
repaint(); 

} 

} 

else if ( mode = Global.MAINT ) { 

// In maintenance mode, the light stays on for 1 second, 
if ( this.count > 0 ) ( 
this.count = 0; 

// Alternate yellow and black. 

if ( this.getColor() — Color.yellow ) 
this.setColor( Color.black ); 
else 

this.setColor( Color.yellow ); 
repaint(); 

) 

) 

) 

public void paint( Graphics g ) ( 

// Draw the background. 
g.setColor( Color.light.Gray ); 
g.fillRect( 0, 0. 50. 165 ) ; 

if ( this.getMode() = Global.NORMAL ) { 

// For any light, black signifies “off”. 
g.setColor( Color.black ); 

// Handle the red light. 

if ( this.getColor() = Color.red ) 
g.sotColor( this.getColor() ); 
g. fillOval( 5. 10. 40. 40 ); 

// Handle the yellow light. 

if ( this.getColor() = Color.yellow ) 
g.setColor( this.getColor() ); 
else 

g.setColor( Color.black ); 
g.fillOval( 5. 60. 40, 40 ); 

// Handle the green light. 

if ( this.getColor() “ Color.green ) 
g.setColor( this.getColorO ); 
else 

g.setColor( Color.black ); 
g.fillOval( 5. 110, 40. 40 ); 

1 

else if ( this.getModeO — Global.MAINT ) ( 

// Red light is always “off”. 
g.setColor( Color.black ); 
g.fillOval( 5. 10. 40. 40 ); 

//Yellow light may be “on”. 

if ( this.getColor() = Color.yellow ) 
g.setColor( this.getColor() ): 
g. fillOval( 5. 60. 40. 40 ); 

// Green light is always “off”. 

g.setColor( Color.black ); 
g.fillOvaK 5. 110. 40. 40 ); 

1 

) 


// Four simple accessor methods. 

public Color getColor() I 
return this.color; 

I 

public void setColor( Color c ) { 
this.color = c; 

} 

public int getModeO { 
return mode; 

I 

public void setMode( int i ) I 
mode = i; 

) 

public void propertyChange( PropertyChangeEvent evt ) [ 

//This is how we get notified of a property change. 

// Make ints out of die old and new values... 

Integer theOldlnt. = ( Integer )( evt .getOldValueO ); 
Integer theNewTnt - ( Integer )( evt.getNewValueO ); 

// ...then compare them. Any change is acceptable, 
if ( theNewint.intValue() != theOldlnt.intValueO ) ( 
mode = theNewint.intValue(); 
this.reset(); 

1 

) 

private void reset() [ 

// In several cases, we need a way to force the lights 
// to a known starting point. 

this.setColor( Color.yellow ); 
this.count = 5; 
this.repaint.(); 

I 

When retrieving the object’s stale, the runner object must be 
created from scratch, since the Thread class is not serializable. 

private void read0bject( ObjectlnputStream s ) throws 
ClassNotFoundException. TOF.xcept ion I 

//Always call the default read method. 

s.defaultReadObject(); 

// Since the Thread cannot be saved, create a new one after 
// startup and state retrieval. 

runner = new Thread( this ); 
runner.start() ; 

} 

) 


Container Apf 

T he DisplayFrame class is provided as a container app for 
the other Beans we’ve built. It is a Frame containing the Display 
(traffic light) and ModeSelector. Figure 1 shows the Beans 
running inside a DisplayFrame object. Since DisplayFrame is an 
application, it can run independently of the BeanBox. 

Listing 4: DisplayFrame.java 


DisplayFrame.java 

// A container app for runtime. 

import java.awt.*; 
import java.awt.event.*; 
import java.beans.*; 
import java.io.*; 
import java.util.*; 

public class DisplayFrame extends Frame implements 
Serializable ( 

// Frame size. 

int width = 125, height - 185; 
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public static void main( String args[] ) l 
//This class can be run outside of the BeanBox. 

DisplayFrame df = new DisplayFrame(): 

) 

public DisplayFrame() ( 

// Call the superclass constructor. 

super(): 

//Wc know how big we want to be. 

this.setSize( this.width, this.height ); 

// Create the traffic light... 

Display display = new DisplayO; 

// ...and the choice menu. 

ModeSelector ms = new ModeSelector(); 

Add the Display object as a listener on the ModeSelector, so 
that it will be nolified when the “mode” value changes. 

ms.addPropertyChangeListener( 

( FropertyChangeListener Jdisplay ); 

// Setup the display area. 

Panel p = new Panel(); 
p. setLayout ( new BorderLayout() ); 
p.add( “Center”, display ); 
p.add( “South”, ms ): 

this.add( p ); 
this.setVisible( true ); 

I 

public Dimension getPreferredSi?.o() { 

//When queried, we know how big we 'want* to be. 

return new Dimension( this.width, this.height ): 

1 

public Dimension gelMinimuraSizeO ( 

// Our preferred size is already the minimum size. 

return this. getPreferredS i /.e (); 

) 

private void rcadObject( ObjectlnputStream s ) throws 
ClassNotFoundException, IOException ( 

//Always call the default read method, 
s.defaultReadObject(); 

1 

) 


Compiling and Running 

You can compile the .java (source) files using the javac 
(Java compiler) tool included in the MRJ SDK Tools folder, or 
using the Java compiler in CodeWarrior or Visual Cafe. You can 
then optionally create a .jar (Java ARchive) file containing the 
resulting .class (output) files. 

The archive for this article includes the .java and .class 
files (in separate directories), and individual .jar files containing 
each Bean and Global.class. In addition, the manifest directory 
contains manifest files for each of the classes, for use in 
building JAR files. You can also combine the manifests and 
classes into one big JAR file. 

To run the program, drag the file Display frame, class onto 
the JBindery application icon, which is located in the MRJ SDK 
JBindery folder. Once JBindery launches, it will display 
“DisplayFrame” in the class name field. (This field specifies the 
name of the class to run at application startup; that class must 
contain a main() method.) Click OK to run the program. 


To mn inside the BeanBox, add the .jar files to the jars 
directory on your hard drive. Then, launch the BeanBox 
application. It should open and read the .jar files, and display the 
Beams in the palette on the left side. It will write an error message 
to the console stating that Global.jar does not contain any Beans. 
This is not a problem, since we know that Global is not a Bean, but 
rather a supporting class. 

Conclusion 

Java Beans should l>e reusable, customizable, and packaged 
in JAR files. As Bean development tools become more 
widespread, developers will find it even easier to create custom 
apps by combining Beans in new' ways. Bean development 
allows an incremental, flexible approach which should make it 
easy for all developers to participate. 
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by Jessica Courtney <managing_ed@mactecb.corn> 


The YAAF Application Framework 

The PandaWave has announced the release of the YAAF 
Application Framework, a freeware C++ framework for 
developing cross-platform applications. 

What is YAAF? 

YAAF stands for “Yet Another Application Framework.” It is 
a C++ YAAF is designed to allow the easy development of cross¬ 
platform applications for the Macintosh OS, Windows 95/98 and 
Windows NT, and X Windows. Written in C++, YAAF provides a 
basic core framework for working with windows, views, menus, 
and controls in a portable fashion. 

YAAF is copyright ©1998 by William Woody and The 
PandaWave, all rights reserved. YAAF is released under the 
GPL Library License, meaning that you may build applications 
using YAAF and resell them even for commercial purposes. 
You may also modify and distribute the YAAF libraries, but 
only as free software—while you may resell the YAAF libraries, 
you must do so under the GNU LGPL. For more information, 
please see the GPL Library License. 

YAAF is currently used by The PandaWave as the basis for 
all of our application development. From BugLink to World 
Calendar and xt, we are using YAAF as our core technology 
for quickly developing cross-plat form applications. By “eating 
our own lunch”, so to speak, we hope to continue 
development on YAAF and continue providing the YAAF 
libraries for free to the developer community. 

YAAF is available for download from the Info-Mac archives 
and from the Panda Wave’s home page. The YAAF distribution file 
also contains YAAF Constructor, an application used for laying 
out windows and dialog boxes, and xt, a simple text editor. 
Complete sources for YAAF, YAAF Constructor, xt and all utilities 
for Macintosh, Microsoft Windows and X (compiled under 
Redhat for Intel) are all provided. 
<http://www.pandawave.com/yaaf/> 

Bear River Associates offers Macintosh Software 
Maintenance Outsourcing Services 

Bear River Associates announced today that it is available 
for handling outsourcing arrangements with software 
publishers and other companies who need their Macintosh 
applications maintained but no longer want to maintain the 
staff to do that internally. These services will enable software 
publishers and other organizations to entrust their Macintosh 
development needs to the oldest Macintosh development 


company around. Bear River has been developing Macintosh 
software since 1985, making it the oldest Macintosh 
development company in existence. 

Bear River has completed more than two hundred 
projects developing Macintosh, Windows and internet 
software development projects for clients such as Apple 
Computer, Microsoft, IBM, America Online, Ernst & Young, 
LiveWorld Productions and Inclusion. Bear River Associates 
offers desktop development services in addition to Internet 
development services. 

<http://www.bearriver.com>. 

SpotCheck 1.1.1 

GenieWorks has announced a promotional price for 
SpotCheck 1.1.1. Finally, there is a java editor with a REAL 
difference and its only US$20 for a limited lime. This is not 
just about color-coded syntax and code indentation... this is 
much more. 

SpotCheck is designed to help a Java programmer produce 
correct code without relying on confusing and untimely 
feedback from a compiler. 

Specifically, SpotCheck identifies syntax errors and semantic 
errors (undefined names, type mismatches, etc.) — those errors 
normally returned by a compiler. This analysis is performed after 
each edit, giving the programmer immediate feedback on errors. 
Now, you only need to compile to produce executable code. 

SpotCheck provides a host of additional features, including: 

• Smart links to name declarations 

• Cross-referenced Java APIs 

• Editing with popup menus 

• Interfaces to helper apps to compile & run 

• Hierarchical project browsing 

• Full support for the Javal.l.x language and APIs 

• Single command, project imports 

<http://www.genieworks.com/> 

Announcing Internet ToolKit v2.0 eor 4D 

Foresight Technology, Inc. announced that it is now 
distributing Internet ToolKit (ITK) v2.0 for Windows or 
Macintosh. Published by JCA S.A. of France, ITK is an 
inexpensive, yet extremely powerful external for 4th Dimension 
(4D). This is ITK’s first major release since 1996 and brings many 
new features and improvements. 
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Internet ToolKit for 4D is the best-selling TCP/IP 
connectivity product for 4D. It allows any developer to send or 
answer requests using TCP, IJDP or even ICMP; thus allowing 
the development of any type of industry strength Internet or 
intranet servers or clients within 4D V3 or V6 on Windows or 
Macintosh. ITK for 4D ships with many examples and demos 
handling the most common protocols (web, email, FTP, etc.). 
<http://www.a4softec.com> 

<http://www.foresight.com> 

General Edit 1.0.2 Debugs and Analyzes Complex 
File Formats 

Quadrivio Corporation announced General Edit 1.0.2, an 
update to the file utility designed to help Mac OS programmers 
view or edit data files with complex binary formats. The new 
version handles recursive formats such as Quicklime. A free 
updater for registered users and the $195 on-line version are 
available from Quadrivio’s web site. 

General Edit, introduced in January, has become a valued 
addition to the toolbox of Mac OS developers. Users report 
saving days of debugging effort through the utility’s ability to 
display simply, clearly, and interactively the contents of 
complicated data structures. 

The tool is a powerful alternative to simple hex or ASCII 
file editors. The user types familiar, C-like statements to 
specify the file format. The format is checked and compiled 
interactively and the tool immediately displays the file’s 
contents in one or more formats. The file’s format 
specification can be saved separately and re-used. The new 
version ships with example definitions for portions of the 
PICT, TIFF, and QuickTime file formats. 
<http://www.quadrivio.com> 

Tangent Systems of San Diego Annouces New 
Company Name 

Tangent Systems of San Diego annouced that it has 
renamed its company to Tritera, a Software Development and 
Consulting company based in San Diego, California. It was 
originally formed in August 1993 as a general partnership. Tritera 
provides customized software development for Macintosh, 
Windows, Unix, and embedded systems using C, C++, CPX, and 
Java programming languages. The company has provided 
custom software development services for several Fortune 500 
companies on a range of projects. 

Tritera is the developer of BuildSim, an Integrated 
Development Environment for Simulation and Control System 
Development. Developers will enjoy the how easily systems can 
be modelled, simulated and tested. BuildSim was developed 
with students, engineers and scientists in mind. Its easy -to-use 
interface masks a sophisticated set of tools for simulation and 
data analysis. Complex dynamic models and control systems can 
simulated and data collected and plotted. BuildSim has been 
designed to make “tinkering” in the modelling/simulation world 


easy. On top of that, several productivity tools have been 
carefully designed to make it a truly unique and powerful 
application for developing and deploying simulations and 
process control systems. 

BuildSim 2.0 Bronze Edition is Free, Downloadable from 
the T ritera website. BuildSim is delivered via internet as a Bronze 
Edition and can be upgraded to increasingly more powerful 
editions (Silver, Gold and Platinum) via password. BuildSim has 
many application areas including Education, Robotics, 
Electronics, Physics, Engineering Design, Process Control, and 
Simulation. Scientists, Engineers, and Engineering Students will 
find BuildSim powerful yet easy to use. Each edition of BuildSim 
provides more capabilities, functions and tools for system 
modelling, simulation and deployment. The Bronze Edition is 
free while the Silver, Gold and Platinum editions will have 
competitive price break points. 

<http://www.tritera.com> 

Tenon Enhances Unix for Power Macintosh and 
Lowers Price 

Santa Barbara, CA, July 27, 1998. Tenon Intersystems is 
shipping an update to its Unix for Power Macs. Power MachTen 
4.1.1 is a POSIX-compliant, BSD 4.4 Unix, with a Mach kernel 
foundation, that operates in concert with the Macintosh 
Operating System. The new Power MachTen 4.1.1 release 
includes updated software development tools, enhanced 
performance and security, and a dramatic price reduction. 

Power MachTen 4.1.1 includes a native fast file system, an 
enhanced suite of Unix software development tools based on the 
latest GNU gcc 2.8.1, including a validated Ada compiler, C, 
Objective-C, C++, Fortran and Java (kaffe), and a high- 
performance X11R6 display and development environment with 
an OpenGL option. MachTen is a multiuser system with remote 
login capabilities that supports SUN’s Network Information 
Service (NIS+), includes standard Unix filesharing (NFS), a full 
complement of Unix networking services (Apache web service, 
DNS bind, FTP service, mail and POP mail), a suite of popular 
scripting tools (Perl, tcl/tk, MacPerl), popular editors (vi, emacs, 
BBEdit Lite, Alpha), and hundreds of standard Unix applications 
and utilities, including secure shell. 

MachTen is a powerful Unix development platform that is 
being used by third party vendors to bring new solutions to the 
Macintosh. By licensing Tenon’s Unix libraries, developers have 
been able to bring sophisticated Unix software to Mac OS, even 
in advance of Rhapsody or Mac OS X. MachTen is being used by 
web developers to create Apache modules for Tenon’s top¬ 
performing Mac OS web server, WebTen. 

Power MachTen can be purchased either directly from Tenon 
or as part of a G3 Unix Workstation bundle from FGM, SciTech 
International, and others. The software is US$495 for corporations 
or individuals. The academic price is $250. The OpenGL option is 
$199; academic, $149. Quantity discounts are available. 
<http://www.tenon.com/products/machten> 
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by Sieve Sisak 





Smarter ZoomWindows 

Here’s a painless substitute for 
ZoomWindow. I originally wrote the 
SmartZoomWindow wrapper to add multiple 

M monitor support to ZoomWindow. Recently I 
tweaked the code to compensate for Mac OS 
8 “fat borders” (actually it should work 
correctly with any WDEF geometry.) 

I inset the zoom out by 3 pixels. I do 
this because some displays still have 
rounded corners that will crop the window’s corners. 
Additionally 1 like to leave a small gap arotind the edge of a 
window so I can click into the Finder. If you desired to adjoin 
the window with the Menubar and display edges set 
klnsetZoomOut to zero. 

Remember to compensate for “fat lx>rders” in your window 
position and window staggering routines. 


Public Interface 

enum { 

klnsetZoomOut = 3 

}; 


void SmartZoomWindow( 

WindowPtr targetWindow, 
short partCode, 

Boolean bringFront); 

Implementation 

static void 
_LocalToGlobalRect( 

Rect ‘targetRect) 

I 

LocalToGlobal((Point*)(&targetRect->top)); 
LocalToClobal((Point*)(&targetRect >bottom)); 


void SmartZoomWindow( 
WindowPtr targetWindow. 
short partCode. 

Boolean front) 

( 

GrafPtr savePort; 
CDHandle dstGDevice; 
GDHandle testGDevice: 
Rect srcRect; 

Rect dstRect: 

Rect testRect; 
long dstArea; 
long testArea: 
short titleHeight; 
short borderWidth: 


if(targetWindow) 

I 

GetPort(&savePort); 

SctPort(targetWindow); 

if (partCode = inZoomOut) 

( 

srcRect = targetWindow >portRect; 

LocalToGlobalRect(fcsrcRect); 
titleHeight = srcRect.top - 1 - 

(*((WindowPeek)targetWindow)->strucRgn) >rgnBBox.top; 
borderWidth = srcRect.left - 1 

(*((WindowPeek)targetWindow) >strucRgn)*>rgnBBox.left; 
srcRect.top -= titleHeight; 
dstArea = 0; 

testGDevice ■ GetDeviceList(); 

while(testCDevice) 

I 

if(TestDeviceAttributc(testGDevice, screenDevice)) 

( 

if(TestDeviccAttribute(testGDevice, screenActive)) 

( 

ScctReet(fcsrcRect. & (‘testGDevice)->gdRect, 

&testRect); 

testArea* (long)(testRect.right testRect.left) * 
(long)(testRect.bottom - testRect.top); 
if(testArea > dstArea) 

( 

dstGDevice = testGDevice; 
dstArea = testArea; 

) 

1 

1 


testGDevice ~ GetNextDevice(testGDevice); 

) 

if(dstGDevice “ GetMainDeviceO) 

( 

titleHeight += GetMBarHeight(); 

1 


) 


dstRect “ (‘dstGDevice)->gdRect; 
dstRect.Lop += titleHeight + klnsetZoomOut; 
dstRect.left += borderWidth + klnsetZoomOut; 
dstRect.right -* borderWidth + klnsetZoomOut; 
dstRect.bottom -= borderWidth + klnsetZoomOut; 

(‘(WStateDataHandle)((WindowPeek)targetWindow)- 

>datallandle) >stdState = dstRect; 


ZoomWindow(targetWindow, partCode, front); 
SetPort(savePort): 


Craig Marciniak 
<craig@marciniac.com> 
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TOOLS OF 
THE TRADE 


by John Schettino 

Edited by the MacTech Magazine Editorial Staff 


Resorcerer: What’s New in 2.2 


Reviewing the latest 
version of Resorcerer 


Resorcerer Overview 

Resorcerer is a professional quality 
resource editor that uses a GUI. It 
distinguishes itself from Apple’s own free 
ResEdit in both power and safety. I’ll toss 
in ease of use, to boot. It’s better than Rez 
because it has a traditional Mac GUI. If 
you’re doing professional development, 
and you spend a lot of time creating and 
editing resources, you owe it to yourself to 
take a close look at Resorcerer. 

You can find a MacTech review of 
Resorcerer in Volume 10, Number 4, or at 
<http://www.mactech.com/articles/mactech/Vol.10 
/10.04/Resorcerer-2/text.html>. 

The 2.2 version, recently release by 
Mathemaesthetics, Inc., builds on the 
current product by adding: 

• a single instruction PPG disassembler, 

• an Alias editor, support for Appearance 
in the Dialog editor, 

• a grab bag of other new features, and 

• a host of bug fixes. 

The 2.2 version is available as a free 
upgrade from version 2.0, off the 
Mathemaesthetics web site at 
<http://www.mathemaesthetics.com/>. 


New Stuff 

As an incremental version upgrade, there are just a few new 
items in 2.2. Some point to future directions, while others just 
round out the already impressive feature set from 2.0. 

Whatza extlwi? 

'Hie Value Converter now supports a preview of what you’ll 
see in a later version of Resorcerer. You enter the opcode (as hex, 
octal, unsigned, or any other format) into the Value Converter, 
and you get back the disassembled PPG instruction, an English 
expansion of the opcode mnemonic, and then a nice description 
of what the instruction is actually doing. The information is based 
on that published in “The PowerPC Architecture — A 
Specification for a New Family of RISC Microprocessors.” As it 
stands, its purely a novelty item, unless you have a burning desire 
to know that opcode 0x5403300 is mnemonic extlwi. 
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Figure 1. Value Converter Showing PPC disassembly. 


John Schettino is an author and Principal Member of the Technical Staff at GTE Laboratories, Inc. He is the co-author of the 
books BASIC for the Newton: Programming for the Newton with NS BASIC, and AppleScript Applications: Building Applications 
with FaeeSpan and AppleScript, both published by AP Professional. His new book. CORBA 2 For Dummies,, published by IDG 
books, is due out in September. He is also a contributing editor for the Handheld Systems Journal where he writes about 
Windows CE programming. You can reach liim via http://members.aol.com/pdcjohns. 
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Whal il shows is that, coming soon to a new release, will he 
a decent PPG disassembler that will also be able to help explain 
what the opcodes are doing. 

AKA Alias Editor 

The Alias editor lets you view, and update a I is resources. It 
uses the Alias Manager to get and update its information, since 
the alis resource is officially undocumented. Apparently it 
doesn’t get what it expects from System 7.5.5, since it does not 
seem to display the correct information for me. 1 know, I really 
should upgrade, but I was a little surprised that Resorcerer didn’t 
work as advertised here (for me, on an older yet not archaic- 
version of Mac OS) or at least detect that it couldn’t work, and 
display an error message! Here’s what Resorcerer could tell me 
about my alis resources: 


ifHH alis 0 “BBEdit 4.0 alias” from BBEdit 4.0 alias 

Signature Zone: L 

IbxOGOOOOOu I Server : john schettino's mac 

Volume : Mac HD 

Path to Alias Target _ 


[ Set Alias ) [ Update ) [ Cancel j 

Figure 2 Not Quite An Alias Editor For System 7.5.5. 

The Appearance of a Dialog Editor 

The Dialog editor shows Appearance Controls during 
layout, and does a better job of sizing those controls when you 
specify the Use Rest Size command. At least that’s what it claims 
to do. Again, I’m hampered by lacking Mac OS 8.0 or later, and 
this feaLure doesn’t work without il. 

I think this points out a minor drawback of the approach 
taken by Resorcerer: Specifically because it is a GUI based 
resource editor, and it uses the system services to provide 
information (for aliases and appearance controls, at least) you 
cannot use it to edit Mac OS 8.x specific resources on a pre- 
Mac OS 8.x machine. It’s not a major drawback, but it is 
something I hadn’t originally considered. Given the improved 
safety and accuracy using system service s provides, its a 
reasonable tradeoff. I’m off to upgrade my OS! 


already supported taking a screen shot and inserting it into a 
new PICT resource. Now you can press the w key to resize 
the screen shot area to match the entire frontmost window. 
That’s handy. 

There’s now a way for you to edit TMPL resources, and the 
ability to edit System 8.2 icon suite resources. For those of you 
who use AppleScript in the development process, Resorcerer 
adds the compare newer file command: 

tell application "Resorccrer® 2.2 Demo" 

set theDiff to compare newer file “VersionA.rsrc" older file 
“VersionB.rsrc” with return differences 
end tell 

Bugs Begone 

There is a list of 28 bug fixes in the 2.2 release notes. 
You can be sure that if they’re willing to admit to 22 bugs, a 
couple more were also quietly exterminated under the cover 
of darkness. 

Conclusion 

Resorcerer retains its position as a well supported and 
maintained resource editor for professional programmers. If 
you prefer using a GUI editor, Resorcerer has so many obvious 
advantages over ResEdit that it is well worth the cost. The 2.2 
release offers modest new features, a fair number of bug fixes, 
and a very attractive upgrade cost of $0. 

If you already have version 2.0, browse on over to their 
web site and get the free 2.2 update. If you’re new to Resorcerer, 
then download the 2.2 demo version. It’s a completely 
functional version, with the save command disabled. See what 
you’ve been missing. 

Product Information 

Resorcerer is still $256 (get it? 256 — or $0x100 in 
hexadecimal dollars — I love a company with a sense of 
humor!) and comes with a 60 day money-back guarantee. 

Mathemaesthetics, Inc. 

P.O. Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 

Fax: (303) 440-0504 

sales@mathemaesthetics.com 

http://www.mathemaesthetics.com 

HQ 


Something For Everyone 

There are a host of minor updates in this release. The 
File window’s resource name display has been expanded (it 
now knows around 100 classes). For you Code Warriors, it 
supports the Cmd-D to discard and Cmd-S to save keyboard 
commands when it displays Save/Discard alerts. Resorcerer 
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And, you know 
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Professional Software Developers 

Looking for career opportunities? 
Check out our website! 

Nationwide Service 
Employment Assistance 
Resume Help 
Marketability Assessment 
Never a fee 

Scientific Placement, Inc. 

800-231 -5920 800-757-9003 (Fax) 

das@scienlific.com 


Help Make MacTech Work 


Here at MacTech Magazine, we rely heavily 
on outside writers for most of the material 
that appears in our pages. If readers did not 
participate in the magazine, sending us their 
ideas and taking the time to write articles, 
there would be no MacTech . MacTech 
Magazine is not a staff of writers sending a 
constant stream of one-way messages 
outwards; it's a living, evolving network of 
readers conversing with one another, 
educating one another, sharing their 
knowledge, their experience, their interest, 
their trials and tribulations and joys and 
successes in the constantly unfolding story 
of programming the Macintosh. MacTech 
Magazine doesn’t just happen: it’s what the 
community makes it. If we carry reports of 


future trends and technologies, if we leach 
useful methods, if we review new books 
and tools, if we provoke thought, provide 
help, ride the wave of current interests and 
concerns, it is only because we reflect the 
thoughts of our readers, who speak 
through our pages. 

You are invited to involve yourself in 
this exciting conversation amongst readers. 
No matter who you are. no matter what 
your credentials may be, if you have a tale 
to tell, a trick to share, a technique to teach, 
we want you to consider joining the family 
of those who write for MacTech. 

Don’t just wait for a topic to be covered 
or a technique explained in MacTech! Take 
responsibility! Write us an article yourself! 


To write for MacTech , just send for our 
Writer’s Kit. It’s a Microsoft Word file 
containing the Styles you need to use, and 
giving lots of helpful advice and information, 
including all the legal stuff. You can let us 
know what you’re writing about, or, if you 
want to. you can just write the article and 
spring it on us when it’s done. [Note: We 
also have a need for people willing to make 
themselves available to write occasional 
product/lxx)k reviews.] If we publish your 
article, you'll lx? paid for it! 

Write to us, the editorial staff, at 
editorial@mactech.com (or one of the other 
addresses listed on page 2 of the magazine). 
Take the future of MacTech Magazine into 
your own hands! 

for IbrMlMt 
rrogrommtn 0 IfttrUtpen 
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Don't let your projects run you down. Do what the professionals do. NetProfessional Magazine 
is where web developers and network administrators look for answers. Each issue provides you 
with practical and detailed solutions to real world problems, extensive how-to articles, in-depth 
product reviews, practical tutorials, tips, techniques, reliable technology summaries, and more! 


Try a RISK FREE 
subscription and see for 
yourself — at the low price 
of only $19.95 for six issues 


PROFESSIONAL 


Phone: 800/622-3381 • Outside US/Canada: 805/494-9797 
Fax: 805/494-9798 • E-mail: orders@netprolive.com 
http://www.netprolive.com 
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The Little Framework that Could 


Getting Started with C++ 


Code reuse was one of the key motivating forces behind the 
development of object-oriented programming. Tt's a simple idea, 
really — come up with a way to organize code so that conceptually 
separate pieces are independent and self-contained. Then, since 
these pieces don't rely on other pails of an application, they can be 
reused in multiple projects without modification. 

The obvious next step in this evolution is the 
development of application frameworks, and the idea here is 
simple, too: most Macintosh applications, for instance, have a 
lot of code in common — they initialize managers, track 
mouse clicks in menus, and use scroll bars. This is where a 
framework comes in — it collects commonly-used code and 
organizes it so that you can develop an application by 
focussing on the parts which make your application distinctive 
while ignoring the mundane. This frees you from the burden 
of writing the same code over and over, and provides you 
with well-debugged code to do the dirty work. This all sounds 
great — so you may be asking, “what’s the problem?" 

MacZoop 

Beginning C++ programmers on the Mac face a bit of a 
Catch-22. On the one hand, they need to be able to test out 
small stretches of code while they are learning, but there really 
is a lot of work to be done just to get a small application up and 
running. So, they could really benefit from a framework — it 
would relieve them from writing support code which they don’t 
yet feel confident writing, and would allow them to be pretty 
sure that if something doesn’t work then it is a problem with 
their code and not, say, that they forgot to initialize TextEdit. 
But, frameworks such as Apple’s MacApp and Metrowerks’ 
PowerPlant were not designed with the beginner in mind — 
they were designed for industrial-strength commercial 
application development. (For instance, the front end to the Mac 
version of Netscape Navigator is PowerPlant-based.) Despite 
excellent documentation, they can be overwhelming, especially 
for someone who is just learning what inheritance and 
polymorphism are all about. 

This is where MacZoop comes in. It is a small (well, maybe 
medium-sized) Macintosh application framework generously 


developed and supported by Graham Cox, and it was specifically 
designed to be a learning tool for those just starting out with C++. 
And, in the spirit of enriching the Macintosh community, it’s free. 

MacZoop! 

<http://www.warwick.ac.uk/~corbe/MacZoop/MacZoop.html> 

MacApp 

<http://developer.apple.com/dev/tools/macapp/index.html> 

Metrowerks (PowerPlant) 

<http://www.metrowerks.com/> 

In fact, without any additional code MacZoop builds into a 
working application. The application doesn’t do much, but it has 
File and Edit menus with the usual menu items, and you can 
open new (empty) windows which are movable, zoomable, and 
resizable, and they tile nicely across the screen, just as you would 
expect from a Mac application. This may not sound like much, 
but any Mac programmer knows how much effort it takes to set 
up such tilings, and how hard it can be for a beginner. This lets 
them build their code in lop of something which already works. 

Graham has included a full bag of goodies to help you along. 
There is an electronic manual, just shy of 200 pages, which uses 
color more effectively than any other technical documentation I 
have seen. It provides a compact introduction to the key concept 
of C++ and of programming the Macintosh in general, and really 
touches on most subjects that a first-time Mac programmer needs 
to have under his belt. Also, there is a small demo application 
showing off many of its main features, and a full-featured paint 
program which serves as a more extensive example. (Both, of 
course, come with full source code, and the manual has detailed 
instructions for compiling the framework using CodeWarrior.) 

Harnessing the Power of Resources 

MacZoop sports a wealth of very clever features which make 
it useful beyond its role as a learning tool, and it warrants a look 
from more experienced programmers as well. For example, if 
you create a window with one of the traditional floating-window 
WDEFs, it floats — it stays above all other windows in your 
application, and hides itself when your application goes into the 
background — you don’t have to worry about the details. It also 
takes full advantage of ResEdit as an interface editor; for instance, 
it provides two separate methods (one based on TCL and one on 


70 


MacTech Online 


MAcfTEcii • September 1998 













PLATFORMS: APPLE SYSTEM 7 


MacApp) for associating commands with menu items, so that 
after setting up your resources you can forget about your menus 
and think in terms of commands that your classes understand. 
ResEdit is also used to create enhanced dialogs, with icon lists 
or scrolling text boxes installed as easily as any other control. 

A few other niceties round out the package, and are worthy 
of special mention. The framework comes with its own small set 
of container classes and avoids any use of the STL. This seems 
to violate the spirit of code reuse, since it duplicates functionality 
already available as part of the language. But it is actually a 
clever move — it introduces the concept of containers and 
templates without requiring a full understanding of the ins and 
outs of the STL, and it avoids the code bloat often associated 
with it. Finally, there are many utility classes which make things 
like creating custom icons or displaying JPEGs a snap. 

Extra Toppings 

Well, l hope I’ve given you a sense of what MacZoop lias to 
offer to beginners and to experts alike — there are a multitude of 
features that I didn’t get to mention. In addition to the core 
distribution, there are a few must-have items contributed by other 
authors. M. I Hi Kusterer has written an extensive set of pane classes 
specifically for MacZoop, which allow you to organize elements of 
your visual interface in a natural, hierarchical manner. IJli is also 
developing Resurrection, a free resource editor for use with 
MacZoop, written (of course) using MacZoop itself. Finally, Joe 
Strout has a smaller set of pane classes, which work with MacZ(x>p 
and with his own framework M<x.)f, which is much smaller than 
’Zoop and which would also be well-suited to a beginner. 

Uli's MacZoop Classes 

<http://www.weblayout.com/witness/ZoopClasses.htm> 

Uli's Resurrection 

<http://www.weblayout.com/witness/Resurrection.htm> 

Joe's MacDev Page (Pane Classes, Moot, etc.) 
<http://www.strout.net/info/coding/macdev/intro.html> 

The Future 

l encourage you to give MacZoop a look, or to point it out 
to your friends who are just beginning to tinker with 
programming on the Mac. Professional programmers will at some 
point want to learn about larger frameworks, but MacZoop will 
introduce you to concepts that you can take with you when you 
move on, and it’s a rich source of code snippets and example of 
how to do things the “right” way. This is an especially exciting 
time to be a Mac developer, with the advent of Mac OS X and 
ever-faster hardware, and I hope that MacZoop and the work of 
other generous folk can help open the door to non-programmers 
wishing to try their hand. Graham intends to make MacZoop fully 
Mac OS X compliant as soon as the API is finalized (support for 
Appearance and Navigation Services is in place now), and he has 
already begun work on a gaming framework built around 
MacZoop. It should all be a lot of fun. 

These and piles of other links are available from the 
MacTech Online web pages at <http://www.mactech.com/online/>. 
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START with the 
most advanced client- 
side SDK on the 
market: c-tree* 5 Plus 
at $895. 

• Complete “C” Source code 

• ROYALTY FREE 
(Client Side) 

• Multiple supported 
protocols 

• Fast, portable, reliable 

• Powerful features like 
transaction processing 

• Win95, NT, and 
Windows 3.1 ready _ 

DUI 

ADD a strong, 
multi-platform, 
industrial-strength 
Server that supports? 

• File mirroring 

• Heterogeneous networking 

• Automatic disaster recovery 

• Multi-threaded design 

• Best price/performance 
available: from $445- $3745 


RESULT? 

A solid, economical, 
easily deployable 
product that fits 
your needs. 

• Portable 

• Scalable 

• Exceptional Performance 

• Flexible 

• Easy Server distribution 

• Convenient OEM terms 

FAIRCOM 

Server 


Heterogeneous 
TCP/IP Network 


You can’t find a better client SDK with these features! 
Over sixteen years of proven reliability and performance. 
No one else supports over 30 platforms in this price range! 


c-tree Plus® 

• Complete C Source 

• Single/Multi User 

• Client/Scrvcr (optional) 

• Full ISAM functionality 

• No Royalties 

• Transaction Processing 

• Fixed/Variable Lengtli Records 

• High Speed Data/Index 
Caching 

• Batch Operations 

• File Mirroring 

• Multiple Contexts 

• Unsurpassed Portability 


FairCom® Server 

• Clicnt/Servcr Model 

• Transaction Processing 

• Requires <2MB RAM 

• Online Backup 

• Disaster Recovery 

• Rollback • Forward 

• Anti-Deadlock 
Resolution 

• Client-side “C" Source 

• Multi-threading 

• Heterogeneous networking 

• File Mirroring 

• OEM/Source Available 


FOR YOUR NEXT PROJECT CALL FAIRCOM: YOU 
CANT FIND A BETTER HETEROGENEOUS 
CLIENT/SERVER SOLUTION! 




d-tree™ 
r-tree® 
ODBC Driver 
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U.S.A. phone (573) 445-6833 fax (573) 445-9698 
EUROPE phone (035) 773-464 fax (035) 773-806 
JAPAN phone (0592) 29-7504 fax (0592) 24-9723 
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Innovation On Display sm 


A MITSUBISHI 

DISPLAY PRODUCTS 


Introducing Diamond Scan® Displays Starting Under $250. 
Mitsubishi’s new line of Diamond Scan displays offer the perfect combination 
of quality, performance and reliability. And with low pricing across the entire 
Diamond Scan line, Mitsubishi is an even greater value. So now you won’t ever 
have to sacrifice performance for a lower price. Mitsubishi also backs each 
Diamond Scan display with a full 3-year warranty and service and support pro¬ 
grams thar are already the best in the business. It all adds up to a lasting, quality 

investment. Get all the 


Diamond Scan details - 
including our multimedia 
displays - by contacting 
Mitsubishi Electronics today. 


USA: 800-843-2515 . Canada: 800-387-9630 . QWIKFAX: 800-937-2094 
World Wide Web: www.mitsubishi-display.com/pb/mtc/ds 


Diamond Scan 70 

• 17" CRT/16.0' DVI* 

• 1280x 1024/65 HzNI 

• 0.28 mm dot pitch 

Diamond Scan 70M 

• 17 CRT /16 0 DVI" 

• 1280 x 1024/65 Hz Nl 

• 0.28 mm dot pitch 

• Headphone jack and two three-watt 
front-firing speakers 

Diamond Scan 90e 

• 19“ CRT/18.0 DVP 

• 1600x 1200/75 HzNI 

• 0.25 mm dot pitch 

• USB upgradability 



Microsoft 
Window* flit 


Mac OS 



June iflaa 

Diamond Scan 15VX 


OIW8 Mitsubishi Electronics America, Inc Diamond Scan is a registered trademark n f Mitsubishi Electronics 
America, Inc. Microsoft, Windows and the Windows logo aie legistered trademark* of Microsoft CVirporanon. 
Muc and flu* Mac OS logo arc trademarks of Apple Computer, luc. Moniloi puces and specifications subject to 
change without notice. *DVI Diagonal Viewable Image. 
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